Summarize a pkgaudit result

Takes a pkgaudit object produced by audit_package() or audit_tarball() and returns summaries of it: how often each rule fired and in which lifecycle phase, how much of the package was read, and the errors, if any. print.summary.pkgaudit() writes them as a sectioned report.

Usage

# S3 method for class 'pkgaudit'
summary(object, path = TRUE, phase = NULL, ...)

# S3 method for class 'summary.pkgaudit'
print(x, path = x$path, ...)

Arguments

object: A pkgaudit object.
path: Logical; if TRUE (default) include the Path: line showing the local filesystem location scanned, with the home directory written as ~. Set FALSE to omit the line. summary.pkgaudit() records the choice in the object it returns; print.summary.pkgaudit() uses that recorded value unless given its own.
phase: Character vector of lifecycle phases to report, e.g. "at_load", or "none" for occurrences that execute in no phase. NULL (default) reports every phase. An unrecognized name is an error.
...: Ignored, for S3 compatibility.
x: A summary.pkgaudit object.

Value

summary.pkgaudit() returns a summary.pkgaudit object: a named list of five summary data frames, the scan metadata, the recorded path, and the recorded phase – the phases the frames were filtered to, or NULL for an unfiltered summary. print() reads it to head the report with the phases asked for, so an empty section is not mistaken for a clean scan.

file_contexts: file_context: each file context found, once.
patterns: phase, rule, n, attck: how often each pattern rule matched, split by the phase its code executes in.
matches: phase, rule, n, attck: as patterns, across the shell and Make-like files.
coverage: status, top_level, type, files, lines: how much of the package was read, grouped by where the files sit and what kind they are. type is what a file was read as, or its extension.
errors: step, file_context, rule, error: the object's errors rows, renamed for display.

print.summary.pkgaudit() returns x invisibly.

Details

The report opens with the same metadata block as print.pkgaudit(), then gives the R Patterns, Shell / Make Matches, Coverage and Errors sections; a section with nothing to report says so. The file_contexts summary is returned for programmatic use but is not part of the report.

Both findings tables are grouped by phase and rule alone. Where a finding sits is on the object's own frames; the report answers what runs, and when. An occurrence executes in every phase its context does, so it contributes one row per phase and n can sum to more than the number of occurrences. Those executing in no phase are gathered under none.

Coverage is counts by status and location, and deliberately no percentage: coverage never reaches 100%. Which files went unexamined is in the object's coverage frame.

Filtering by phase

phase restricts the report to the phases named, and is the only way to narrow it: the summary has already been expanded by phase, so it cannot be subset afterwards. A filtered report names its phases in the header, so it cannot be mistaken for a full scan.

Examples