Package 'biotrace'

Description

write_biotrace_config() writes a BioTrace YAML configuration file. read_biotrace_config() reads one back as an R list. validate_biotrace_config() validates a file against the upstream JSON Schema.

Usage

default_biotrace_config()

default_biotrace_config_text()

write_biotrace_config(
  path,
  config = default_biotrace_config(),
  overwrite = FALSE
)

read_biotrace_config(file)

validate_biotrace_config(file, return_errors = FALSE)

Arguments

Value

• write_biotrace_config(): the absolute path to the written file, invisibly.

• read_biotrace_config(): a list representing the parsed YAML.

• validate_biotrace_config(): TRUE (invisible) when valid and return_errors = FALSE; otherwise a list of error objects (possibly empty).

A list representing the smallest valid BioTrace config.

The default BioTrace configuration as a YAML string.

Stability

Configuration follows version: 1 of the BioTrace configuration schema. The schema reference copy shipped in this package is a verbatim copy of the JSON Schema published by rotsl/biotrace.

Examples

tmp <- tempfile()
write_biotrace_config(tmp, default_biotrace_config())
validate_biotrace_config(tmp)
read_biotrace_config(tmp)

Description

read_biotrace_report() reads the machine-readable JSON report produced by the BioTrace GitHub Action. The result is an S3 object of class biotrace_report with print() and summary() methods.

Usage

read_biotrace_report(file)

validate_biotrace_report(file, return_errors = FALSE)

## S3 method for class 'biotrace_report'
summary(object, ...)

## S3 method for class 'biotrace_report'
print(x, ...)

Arguments

Details

validate_biotrace_report() validates a report file against the upstream BioTrace report JSON Schema.

summary.biotrace_report() returns a compact summary of the report: status, score, finding counts.

Value

• read_biotrace_report(): an object of class biotrace_report (a list with extra attributes holding the source path).

• validate_biotrace_report(): TRUE (invisible) or a list of error objects.

• summary.biotrace_report(): a list with elements status, score, findings_count, blocking_findings_count, files_checked, claims_checked, figures_checked, generated_at, source.

Report shape

The report JSON follows the upstream biotrace-report.schema.json (shipped under ⁠inst/extdata/schemas/⁠). Required fields are schema_version, generated_at, status, score, summary, findings.

Examples

report_path <- system.file("extdata", "example-report.json",
                           package = "biotrace")
report <- read_biotrace_report(report_path)
print(report)
summary(report)

Description

biotrace_version() returns a list with the package version and the upstream BioTrace Action tag this package was designed against. The upstream tag is informational: this package works with the upstream Action at the uses: rotsl/biotrace@v1 ref, which is the tag this package targets.

Usage

biotrace_version()

Value

A list with elements package (character version string), upstream_repo (URL), upstream_ref (Action tag), and upstream_action_version (the package.json version of upstream BioTrace at the time this package was authored).

Examples

biotrace_version()

Description

use_biotrace() initialises BioTrace integration in a project by writing .github/biotrace.yml and .github/workflows/biotrace.yml.

Usage

biotrace_workflow_text(
  path = NULL,
  config_path = ".github/biotrace.yml",
  fail_on = "error",
  ai_enabled = "false",
  include_workflow_dispatch = FALSE,
  upload_report = TRUE,
  extra_inputs = list()
)

write_biotrace_workflow(
  path,
  config_path = ".github/biotrace.yml",
  fail_on = "error",
  ai_enabled = "false",
  include_workflow_dispatch = FALSE,
  upload_report = TRUE,
  extra_inputs = list(),
  overwrite = FALSE
)

use_biotrace(
  project = NULL,
  config_path = ".github/biotrace.yml",
  workflow_path = ".github/workflows/biotrace.yml",
  fail_on = "error",
  ai_enabled = "false",
  include_workflow_dispatch = FALSE,
  upload_report = TRUE,
  extra_inputs = list(),
  overwrite = FALSE
)

Arguments

Details

write_biotrace_workflow() writes the workflow file alone.

biotrace_workflow_text() returns the workflow file content as a character vector (so callers can inspect or post it without writing to disk).

The generated workflow references the upstream Action directly:

uses: rotsl/biotrace@v1

It never references this package itself as an Action, because biotrace is an R package, not a GitHub Action repository.

Value

• use_biotrace(): a named list of absolute paths (config, workflow) invisibly.

• write_biotrace_workflow(): the absolute path, invisibly.

• biotrace_workflow_text(): a character vector (one element per line, no trailing newline) representing the workflow YAML.

Inputs echoed into the workflow

The generated workflow uses these inputs (matching the upstream action.yml of BioTrace v1.x): config, github-token, fail-on, ai-enabled. Other inputs retain their upstream defaults. Pass extra_inputs to add or override inputs.

Examples

tmp <- tempfile()
write_biotrace_workflow(tmp)
cat(biotrace_workflow_text(), sep = "\n")

Description

run_biotrace_github() provides an R-facing way to interact with a GitHub repository that already uses the BioTrace workflow. It does not embed the upstream BioTrace engine, and it does not modify rotsl/biotrace.

Usage

run_biotrace_github(
  repo,
  action = c("list-workflows", "list-runs", "trigger"),
  workflow_name = "biotrace.yml",
  ref = NULL,
  token = NULL,
  token_env = "GITHUB_TOKEN",
  api_url = "https://api.github.com",
  transport = NULL,
  dry_run = FALSE
)

Arguments

Details

The function uses the GitHub REST API via utils::download.file for the read-only parts (workflow listing, workflow runs, run artifacts). For triggering (workflow_dispatch) it requires a token with repo scope (or public_repo for public repositories).

This helper is intentionally narrow: it does not attempt to re-implement GitHub Actions, and it does not claim to execute BioTrace locally. It is a convenience wrapper around the GitHub REST API for the same workflow that use_biotrace() writes.

Value

A list (the parsed JSON response, or the request that would have been issued when dry_run = TRUE). The list always contains a request element describing what was sent.

Authentication

Tokens are read from environment variables only. They are never written to disk, never embedded into generated workflows, and never printed. The lookup order is:

1. The token argument.

2. The environment variable named by the token_env argument (default: GITHUB_TOKEN).

3. The environment variable GH_TOKEN (a GitHub CLI convention).

If none of those is set, the function aborts with a clear error message. It does not silently degrade to unauthenticated access.

Network behaviour

All network access is opt-in. The function never touches the network during package load, during ⁠R CMD check⁠, or during any of the local helpers. The unit tests use a mock transport (the transport argument) so they run completely offline.

Skip-on-CRAN

Tests that exercise the live network path are tagged with skip_on_cran(). The default behaviour when transport is NULL and no token is present is to abort cleanly.

Examples

## Not run: 
# Requires GITHUB_TOKEN set.
run_biotrace_github("rotsl/biotrace-r", action = "list-runs")

## End(Not run)

# Safe, offline: see the request that would be issued.
run_biotrace_github(
  "rotsl/biotrace-r",
  action = "trigger",
  dry_run = TRUE
)