check_project() checks a project folder against the house layout and
prints one line per finding. In a non-interactive R session it quits with
status 1 when any rule fails.
Details
A rule with no finding prints one PASS line. Each finding prints one line:
PASS|WARN|FAIL <rule> <detail>. A count line comes last.
Every rule reads one set of files and their folders:
When
pathis the top folder of a git repository, the set is the output ofgit ls-files --cached --others --exclude-standard. These are the tracked files, and the untracked files that git does not ignore.Otherwise, the set is every file and folder on disk.
Both sets leave out .DS_Store, .Rhistory, .RData, the Word lock
files ~$*, and everything in .git/ or .Rproj.user/.
The rules:
lower_case_names(FAIL): a file or folder name has a capital letter. Everything underbackground/is not checked. These are exempt:README.md,CHANGELOG.md,AGENTS.md,CLAUDE.md,LICENSE,DESCRIPTION, a top-level dotfile, a top-level*.Rprojfile, file extensions, and the initials inmanuscript/manual/vNN_<INITIALS>.docx.run_script_initialises(FAIL): avNN_run.Rat the top level has no callpbn::initialize_project()whoseversionargument is the string"vNN". The detail names each argument of the call thatinitialize_project()does not have.no_active_use_scenario(FAIL): avNN_run.Rat the top level has a callpbn::use_scenario()oruse_scenario(), or the referencepbn::use_scenario, that is not in a comment. A call inside a function body or anifcounts.use_scenario()is for stepping through the script by hand.use_scenario_lines(FAIL): avNN_run.Rat the top level does not have exactly one comment# pbn::use_scenario("<name>", sim = 1)for each scenario ofCFG$scenarios. A comment for another scenario fails too. The detail names each such scenario, with the number of lines when there is more than one. The rule does not check the order.A comment counts only when all of these hold:
It is above the first call
pbn::initialize_project().It is at the top level of the script, not in a function body or a braced block such as an
if.It is the only thing on its line.
It has
sim = 1. Any whitespace between its parts is allowed.
The rule is a WARN with the reason when the script has no call
pbn::initialize_project(), or when pbn cannot readCFG$scenarios.version_items_complete(FAIL): avNN_run.Rhas novNN_functions/, or the reverse.results_contract(FAIL): avNN_results/<scenario>/results.qs2or avNN_results/<scenario>/sim_NNNN/results.qs2failscheck_results(), or aresults.qs2is directly invNN_results/.scenario_checks(FAIL): avNN_results/<scenario>/check.csvhas a value ofpassthat is notTRUE.run_scenarios()writes these files.manual_manuscript_names(FAIL): a file inmanuscript/manual/does not match^v[0-9]{2}_[A-Z]{2,4}[0-9]?\.docx$.manuscript_reads_real(FAIL): an.R,.qmdor.Rmdfile inmanuscript/built/callsread_results()orpbn::read_results()with ascenarioargument that is not the string"real". A call withoutscenariopasses. In.qmdand.Rmdfiles, the rule reads the R chunks thatknitr::purl()extracts and the inline R code.no_local_copy_of_pbn_function(FAIL): a top-level assignment in avNN_functions/*.Rfile defines a function with the name of a pbn export.loc_per_file(FAIL): an.Rfile has more than 1000 code lines, as counted byorg::loc_per_file().no_environment_variables(FAIL): a run script or a file in a functions folder usesSys.getenvorSys.setenv.unknown_path(WARN): the house layout does not name a top-level file or folder. The layout namesvNN_run.R,vNN_functions/,vNN_results/,vNN_test/,vNN_check_functions.R,check_project.Randrun_scenarios.R, among others. A top-level dotfile and a top-level*.Rprojfile are never unknown.
The R parser, not a regular expression, finds the calls, the assignments and the symbols.
check_project() runs project code. To read CFG$scenarios for the rule
use_scenario_lines, it sources the vNN_functions/ folder of each
vNN_run.R with org::initialize_project() in a new R session, as
run_scenarios() does. Each top-level call in those files runs then, for
example a call that writes a file.
The file pbn_allow.txt in the project folder MAY list exceptions. Write
one rule<TAB>path per line, with the path relative to the project folder.
An allowed finding prints as WARN, with (allowed) at the end. An entry
that matches no finding prints as a WARN of the rule pbn_allow.
Examples
home <- file.path(tempdir(), "pbn_check_example")
dir.create(file.path(home, "v01_functions"), recursive = TRUE)
writeLines(
'pbn::initialize_project(version = "v01", home = ".", data_raw = "x")',
file.path(home, "v01_run.R")
)
pbn::check_project(home)
#> PASS lower_case_names no capital letter in a name
#> PASS run_script_initialises every vNN_run.R calls pbn::initialize_project() with its own version
#> PASS no_active_use_scenario no vNN_run.R has an active call pbn::use_scenario()
#> WARN use_scenario_lines v01_run.R: pbn cannot read CFG$scenarios: CFG$scenarios in v01_functions/ must be a data.frame with the columns scenario and sims.
#> PASS version_items_complete every vNN_run.R has a vNN_functions/, and the reverse
#> PASS results_contract every vNN_results/<scenario>/results.qs2 and vNN_results/<scenario>/sim_NNNN/results.qs2 passes check_results()
#> PASS scenario_checks every vNN_results/<scenario>/check.csv passes
#> PASS manual_manuscript_names every file in manuscript/manual/ is named vNN_<INITIALS>.docx
#> PASS manuscript_reads_real manuscript/built/ reads only the real results
#> PASS no_local_copy_of_pbn_function no vNN_functions/ file defines a pbn export
#> PASS loc_per_file no .R file has more than 1000 code lines
#> PASS no_environment_variables no Sys.getenv or Sys.setenv in a run script or a functions folder
#> PASS unknown_path the house layout names every top-level path
#> 12 PASS, 1 WARN, 0 FAIL
unlink(home, recursive = TRUE)
