dsROCrate v0.2.0

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: dsROCrate
 Title: 'DataSHIELD' RO-Crate Governance Functions
-Version: 0.1.0
+Version: 0.2.0
 Authors@R: c(
     person(given = "Roberto",
            family = "Villegas-Diaz",
@@ -33,7 +33,7 @@ Suggests:
     fs,
     knitr,
     MolgenisArmadillo,
-    testthat (>= 3.0.0),
+    testthat (>= 3.1.4),
     withr
 Config/testthat/edition: 3
 Encoding: UTF-8
@@ -50,6 +50,7 @@ Imports:
     rmarkdown,
     rocrateR (>= 0.1.0),
     tibble,
+    uuid,
     vtree,
     xptr,
     yaml

NAMESPACE

@@ -1,13 +1,33 @@
 # Generated by roxygen2: do not edit by hand
 
+S3method(as.data.frame,safe_call)
+S3method(as.data.frame,symbol_registry)
 S3method(audit,ArmadilloCredentials)
 S3method(audit,character)
 S3method(audit,cr8tor)
+S3method(audit,default)
 S3method(audit,list)
 S3method(audit,opal)
 S3method(audit,rocrate)
 S3method(audit_engine,cr8tor)
+S3method(audit_engine,default)
 S3method(audit_engine,opal)
+S3method(backend_logs,opal)
+S3method(backend_options,opal)
+S3method(backend_packages,opal)
+S3method(backend_profile_exists,opal)
+S3method(backend_project,opal)
+S3method(backend_project_exists,opal)
+S3method(backend_project_perms,opal)
+S3method(backend_projects,opal)
+S3method(backend_resource_perms,opal)
+S3method(backend_resources,opal)
+S3method(backend_sys_perms,opal)
+S3method(backend_table_perms,opal)
+S3method(backend_tables,opal)
+S3method(backend_user_exists,opal)
+S3method(backend_users,opal)
+S3method(check_permissions,ArmadilloCredentials)
 S3method(check_permissions,default)
 S3method(check_permissions,opal)
 S3method(extract_safe_data,opal)
@@ -20,6 +40,7 @@ S3method(extract_safe_project,opal)
 S3method(extract_safe_project,rocrate)
 S3method(extract_safe_setting,opal)
 S3method(extract_safe_setting,rocrate)
+S3method(filter_safe_people,opal)
 S3method(flatten_safe_data,default)
 S3method(flatten_safe_data,rocrate)
 S3method(flatten_safe_output,default)
@@ -30,25 +51,37 @@ S3method(flatten_safe_project,default)
 S3method(flatten_safe_project,rocrate)
 S3method(flatten_safe_setting,default)
 S3method(flatten_safe_setting,rocrate)
+S3method(has_symbol,symbol_registry)
+S3method(init,ArmadilloCredentials)
 S3method(init,opal)
 S3method(init,rocrate)
+S3method(is_admin_con,opal)
+S3method(is_audit_con,opal)
 S3method(parse_user_profiles,ArmadilloCredentials)
 S3method(parse_user_profiles,opal)
 S3method(print,cr8tor_bundle)
+S3method(print,safe_call)
+S3method(print,safe_symbol)
 S3method(project_exists,ArmadilloCredentials)
 S3method(project_exists,opal)
+S3method(report,ArmadilloCredentials)
 S3method(report,character)
 S3method(report,default)
 S3method(report,list)
 S3method(report,rocrate)
+S3method(safe_call,call)
+S3method(safe_call,character)
+S3method(safe_data,ArmadilloCredentials)
 S3method(safe_data,character)
 S3method(safe_data,default)
 S3method(safe_data,opal)
 S3method(safe_data,rocrate)
+S3method(safe_output,ArmadilloCredentials)
 S3method(safe_output,character)
 S3method(safe_output,default)
 S3method(safe_output,opal)
 S3method(safe_output,rocrate)
+S3method(safe_people,ArmadilloCredentials)
 S3method(safe_people,character)
 S3method(safe_people,default)
 S3method(safe_people,opal)
@@ -58,6 +91,7 @@ S3method(safe_project,character)
 S3method(safe_project,default)
 S3method(safe_project,opal)
 S3method(safe_project,rocrate)
+S3method(safe_setting,ArmadilloCredentials)
 S3method(safe_setting,character)
 S3method(safe_setting,cr8tor)
 S3method(safe_setting,default)

NEWS.md

@@ -1,3 +1,35 @@
+# dsROCrate 0.2.0
+
+## Breaking Changes
+
+* The audit log tibble returned via `safe_output()` no longer includes a `table` column. It has been replaced by three more granular columns: `kind` (whether the tracked object is a `table`, `resource` or `expression`), `asset` (the resolved table/resource name) and `expr` (the associated R expression, when applicable). Code that reads the `table` column directly will need to be updated.
+
+## New Features
+
+* Added a symbol registry and call-tracking system (`safe_symbol()`, `safe_call()`, `safe_reference()`, `symbol_registry()`) that replaces regex-based parsing of Opal logs, modelling assignments and aggregate function calls as objects and resolving arguments back to the symbols/tables they reference.
+* Added a generic backend abstraction layer (`backend_logs()`, `backend_options()`, `backend_users()`, `backend_projects()`, `backend_sys_perms()`, and others) so internal code no longer calls `opalr::` directly, paving the way for additional backends.
+* Added early Armadillo backend scaffolding: `check_permissions()`, `init()`, `report()`, `safe_data()`, `safe_output()`, `safe_people()` and `safe_setting()` now all have `ArmadilloCredentials` methods, returning clear "not yet implemented" errors ahead of full support.
+* Added `default` S3 methods for `audit()`, `audit_engine()` and `check_permissions()`, giving clearer errors when an unsupported connection object is supplied.
+* Added a `verbose` argument to `check_permissions()` (opal method) to optionally print a success message when permissions are sufficient.
+* Added `print.safe_call()` and `print.safe_symbol()` methods, plus `as.data.frame()` methods for `safe_call` and `symbol_registry` objects, for readable inspection of the new internal tracking objects.
+
+## Improvements
+
+* `safe_people()` now determines admin/auditor status from actual system permissions and group membership, rather than a hardcoded name check against `"admin"`/`"administrator"`, improving compatibility with deployments that use differently named privileged accounts.
+* Permission lookup failures during `safe_people()` now fall back gracefully to an empty result instead of aborting the whole audit.
+* Consolidated backend-version and connection-validation logic into the new generic backend framework, reducing duplication between Opal-specific code paths.
+
+## Documentation
+
+* Removed a vignette section demonstrating direct calls to internal helper functions, which have since been renamed as part of the backend abstraction work.
+* Updated documentation to reflect that `init()`, `safe_data()`, `report()` and related functions now accept either `opal` or `ArmadilloCredentials` connections.
+
+## Internal Changes
+
+* Added test coverage for `audit()`, `audit_engine()` and `check_permissions()`, along with a mock-connection test helper, reducing reliance on a live demo Opal server.
+* Added `uuid` to `Imports`, used to generate unique IDs for tracked symbols.
+* Bumped the `testthat` version requirement in `Suggests` from `>= 3.0.0` to `>= 3.1.4`.
+
 # dsROCrate 0.1.0
 
 ## New Features

R/audit.R

@@ -47,11 +47,22 @@ audit <- function(x, ...) {
   UseMethod("audit")
 }
 
+#' @export
+audit.default <- function(x, ...) {
+  stop(
+    sprintf(
+      "No `audit()` method exists for objects of class: %s.",
+      paste(class(x), collapse = ", ")
+    ),
+    call. = FALSE
+  )
+}
+
 #' @rdname audit
 #' @export
 audit.ArmadilloCredentials <- function(x, ..., intent = NULL) {
   stop(
-    "The audit for Armadillo backend is not currently implemented!",
+    "The `audit()` for the Armadillo backend is not currently implemented!",
     call. = FALSE
   )
 }
@@ -65,21 +76,27 @@ audit.character <- function(x, ..., intent = NULL) {
   }
 
   # attempt loading a `cr8tor` bundle
-  x_obj <- tryCatch(
-    load_cr8tor_bundle(x, ...),
-    error = function(e) NULL
-  )
+  cr8tor_res <- .try_load(load_cr8tor_bundle(x, ...))
+  x_obj <- cr8tor_res$value
+
   # alternatively, attempt loading an RO-Crate
+  rocrate_res <- list(value = NULL, error = NULL)
   if (is.null(x_obj)) {
-    x_obj <- tryCatch(
-      rocrateR::load_rocrate(x, ...),
-      error = function(e) NULL
-    )
+    rocrate_res <- .try_load(rocrateR::load_rocrate(x, ...))
+    x_obj <- rocrate_res$value
   }
 
   if (is.null(x_obj)) {
     stop(
-      "The given path does not point to a valid `cr8tor` archive nor an `rocrate",
+      paste0(
+        "The given path does not point to a valid `cr8tor` archive nor an ",
+        "`rocrate`.\n\n",
+        "  cr8tor bundle error:  ",
+        if (is.null(cr8tor_res$error)) "(not attempted)" else cr8tor_res$error,
+        "\n",
+        "  rocrate error:        ",
+        if (is.null(rocrate_res$error)) "(not attempted)" else rocrate_res$error
+      ),
       call. = FALSE
     )
   }

R/audit_engine.R

@@ -3,9 +3,9 @@
 #' Internal function to create audits for various back-ends.
 #'
 #' @param x This can be a connection to a 'DataSHIELD' server (e.g., object with
-#'     the `opal` class, see [opalr::opal.login()]). Alternatively, a governance
-#'     archive file, representing the intent of a project and associated
-#'     governance details.
+#'     the `opal` or `ArmadilloCredentials` classes). Alternatively, a
+#'     governance archive file, representing the intent of a project and
+#'     associated governance details.
 #' @param ... Other optional arguments, see full documentation for details.
 #' @param project String with project name(s) from which to extra Safe Project
 #'     details.
@@ -26,6 +26,17 @@ audit_engine <- function(x, ...) {
   UseMethod("audit_engine")
 }
 
+#' @export
+audit_engine.default <- function(x, ...) {
+  stop(
+    sprintf(
+      "No `audit_engine()` method exists for objects of class: %s.",
+      paste(class(x), collapse = ", ")
+    ),
+    call. = FALSE
+  )
+}
+
 #' @export
 audit_engine.cr8tor <- function(x, ...) {
   # extract individual components from cr8tor bundle
@@ -57,21 +68,21 @@ audit_engine.opal <- function(
   path = NULL
 ) {
   # local bindings
-  name <- permission <- principal <- NULL
+  name <- NULL
 
   # create RO-Create with the 5 safes profile
   crate <- rocrateR::rocrate_5s()
 
   # validate backend
   validate_backend(x, ...)
 
-  # if `project` is missing, then ~extract all project names~ error
+  # if `project` is missing, then error
   if (is.null(project)) {
     stop("A `project` name is required!", call. = FALSE)
   }
 
   # extract list with all projects to verify `project` contains a valid value
-  ds <- opalr::opal.projects(x)
+  ds <- backend_projects(x)
   server_prjs <- ds[, "name"]
   idx <- project %in% server_prjs
   if (!all(idx)) {
@@ -86,41 +97,30 @@ audit_engine.opal <- function(
 
   # Safe People ----
   # get users' details
-  safe_people_tbl <- opalr::oadmin.user_profiles(x, df = FALSE) |>
-    dplyr::bind_rows() |>
-    dplyr::rename(name = principal) |>
-    # exclude system administrators from the report
-    dplyr::filter(!(tolower(name) %in% c("admin", "administrator")))
-
-  # if any users were found, then verify if they are admin/auditors and exclude
-  if (nrow(safe_people_tbl)) {
-    # extract system permissions
-    sys_perms_tbl <- opalr::oadmin.system_perm(x)
-    safe_people_tbl <- tryCatch(
-      {
-        safe_people_tbl |>
-          dplyr::left_join(sys_perms_tbl, by = c("name" = "subject")) |>
-          dplyr::filter(!(permission %in% c("administrate", "audit")))
-      },
-      error = function(e) {
-        tibble::tibble()
-      }
-    )
-  }
-
+  safe_people_tbl <- filter_safe_people(x)
   if (!is.null(user)) {
     safe_people_tbl <- safe_people_tbl |>
       dplyr::filter(tolower(name) %in% user)
+  }
 
-    if (nrow(safe_people_tbl) == 0) {
-      stop(
+  # an audit report is not meaningful without Safe People details, whether
+  # that's because a `user` filter matched nobody, or because the
+  # permission lookup itself could not be completed
+  if (nrow(safe_people_tbl) == 0) {
+    stop(
+      if (is.null(user)) {
+        paste(
+          "No Safe People details could be found for this project - the",
+          "audit cannot proceed."
+        )
+      } else {
         sprintf(
           "No Safe People details were found for the user: %s!",
           paste0("'", user, "'", collapse = ", ")
-        ),
-        call. = FALSE
-      )
-    }
+        )
+      },
+      call. = FALSE
+    )
   }
 
   crate <- safe_people_tbl$name |>