Assemble a change proposal from a temporary patch

Run a call before and after temporary function patches, assess the graph impact of each patched function, and assemble an advisory handoff. Composes with_patch() and change_impact() without modifying package source.

Usage

propose_change(
  expr,
  patches,
  graph,
  ignore = character(),
  tolerance = sqrt(.Machine$double.eps),
  output_dir = NULL,
  on_secret = c("redact", "abort"),
  overwrite = FALSE,
  store = NULL,
  store_label = NULL,
  store_tags = character()
)

Arguments

expr

A function call to evaluate. Passed to with_patch().

patches

A named list of replacement functions. Passed to with_patch().

graph

An insider_graph, source directory, or installed package name used by change_impact().

ignore

Character vector of top-level fields to ignore. Passed to with_patch().

tolerance

Single non-negative numeric comparison tolerance. Passed to with_patch().

output_dir

Optional directory in which to write proposal.md and proposal.json.

on_secret

How sensitive-looking call or error text is handled. The default, "redact", removes secret-shaped values and values assigned to credential-named arguments from the returned object and both proposal artifacts. "abort" stops before writing or returning a proposal when such text is found.

overwrite

Overwrite existing proposal.md and proposal.json files in output_dir? Defaults to FALSE.

store

An optional insider_store handle (see insider_store()). When supplied, the returned proposal is also recorded in the store via store_save(); the resulting id is attached as its "store_id" attribute. The default, NULL, records nothing, consistent with the store's explicit, opt-in design.

store_label

An optional label passed through to store_save() when store is supplied.

store_tags

Optional character tags passed through to store_save() when store is supplied.

Value

An insider_proposal object containing the comparison, provenance, per-patch impact, advisory recommendation, validation commands, and the output_dir it was written to (NULL when not written to disk).

See also

with_patch(), change_impact()

Examples

dir <- tempfile()
dir.create(dir)
writeLines("helper <- function(x) x + 1", file.path(dir, "code.R"))
helper <- function(x) x + 1
propose_change(
  helper(1),
  patches = list(helper = function(x) x + 2),
  graph = dir
)
#> 
#> ── insideR patch ───────────────────────────────────────────────────────────────
#> Call: `helper(1)`
#> Patched function: `helper()`
#> helper(): session-local function, not part of an installed package
#> 
#> ── insideR comparison ──────────────────────────────────────────────────────────
#> Status: structural_difference
#> all.equal() reports structural differences between custom_result and
#> original_result.
#> 
#> ── Details ──
#> 
#> all.equal():
#> • Mean relative difference: 0.3333333
#> Numeric summary (beyond tolerance = 1.49011611938477e-08):
#> • Max absolute difference: 1
#> • Differing elements: 1 / 1
#> • Differing percent: 100%
#> 
#> ── insideR proposal ────────────────────────────────────────────────────────────
#> Call: `helper(1)`
#> Patched function: `helper()`
#> 
#> ── Comparison ──
#> 
#> ── insideR comparison ──────────────────────────────────────────────────────────
#> Status: structural_difference
#> all.equal() reports structural differences between custom_result and
#> original_result.
#> 
#> ── Details ──
#> 
#> all.equal():
#> • Mean relative difference: 0.3333333
#> Numeric summary (beyond tolerance = 1.49011611938477e-08):
#> • Max absolute difference: 1
#> • Differing elements: 1 / 1
#> • Differing percent: 100%
#> 
#> ── Change impact ──
#> 
#> ── helper ──────────────────────────────────────────────────────────────────────
#> Kind: function | export status unknown | Risk: low
#> Callers
#> Exported: none
#> Internal: none
#> Total distinct callers: 0
#> Method family
#> not identified as an S3 method
#> Related tests
#> none
#> Risk notes
#> • none identified
#> Validation commands
#> • R CMD check
#> 
#> ── Recommendation ──
#> 
#> Recommendation (advisory): local-customization
#> Rationale: Behaviour changed, but no patched function is exported and no
#> high-risk signal was found.
#> 
#> ── Validation commands ──
#> 
#> • R CMD check