Robustifying clang-tidy

Author: gregorgorjanc

.clang-tidy

@@ -0,0 +1,17 @@
+---
+# Stable low-noise gate for pre-commit. Keep this profile focused on
+# correctness and a few numerics/performance checks that are useful for this
+# codebase without depending heavily on LLVM-version-specific style policies.
+Checks: >-
+  clang-diagnostic-*,
+  clang-analyzer-*,
+  bugprone-integer-division,
+  bugprone-incorrect-roundings,
+  bugprone-suspicious-memory-comparison,
+  bugprone-too-small-loop-variable,
+  bugprone-undefined-memory-manipulation,
+  performance-inefficient-vector-operation,
+  performance-move-const-arg
+WarningsAsErrors: ""
+FormatStyle: none
+SystemHeaders: false

README_DEVEL.md

@@ -96,6 +96,7 @@ The current hook set includes:
 * [air](https://github.com/posit-dev/air) to format `R` code
 * [jarl](https://github.com/etiennebacher/jarl) to lint `R` code
 * [clang-format](https://clang.llvm.org/docs/ClangFormat.html) to format `C/C++` code
+* [clang-tidy](https://clang.llvm.org/extra/clang-tidy/) to lint `C/C++` code
 
 Install these tools with your preferred package manager before contributing.
 One macOS setup looks like this:
@@ -113,7 +114,10 @@ brew install air
 # Install clang-format
 brew install clang-format
 
-# Add llvm tools, to PATH
+# Install llvm for clang-tidy
+brew install llvm
+
+# Add llvm tools to PATH
 echo 'export PATH="/opt/homebrew/opt/llvm/bin:$PATH"' >> ~/.zshrc
 ```
 
@@ -191,8 +195,11 @@ Relevant tests are in `RcppTskit/tests/testthat`.
 
 During development,
 start with focused tests for the area you changed.
-Before opening or updating a pull request,
-run the full test suite and package checks.
+Before opening or updating a pull request:
+1) run the full test suite,
+2) ensure package checks pass, and
+3) check test coverage.
+All of these are described below.
 
 ### `R CMD check`
 
@@ -323,6 +330,9 @@ At that point,
 the safest recovery path is usually to create a fresh branch from the latest `upstream/main`
 and then move your commits across with `git cherry-pick <commit>`,
 or simply re-apply the changes manually to the files if that is simpler.
+Another option with many local commits
+is to squash them (see below) into one
+and then rebasing.
 
 After a successful rebase, rerun the relevant tests and checks.
 If you already pushed the branch to `origin`, update it with:
@@ -393,3 +403,12 @@ If you plan to update the vendored `tskit` C library,
 follow the instructions in `extern/README.md` and
 do not edit vendored copies by hand.
 Any changes to that code should go to `tskit` upstream.
+
+## More advanced and thorough testing
+
+The repository pins a low-noise `.clang-tidy` profile.
+For occasional broader `C/C++` audits,
+use `--config-file=RcppTskit/tools/clang_tidy_audit.yaml`
+with `clang-tidy` or `RcppTskit/tools/clang_tidy.py`.
+See `RcppTskit/notes_pkg_dev.Rmd` for a set of unpolished notes.
+The notes also include suggestions on debugging `C/C++` code.

RcppTskit/notes_pkg_dev.Rmd

@@ -167,36 +167,6 @@ To ignore multiple lines use `# nocov start/stop`.
 
 In `Rcpp` code use `// # nocov ...`.
 
-### Debugging C/C++
-
-In `src/Makevars.in` uncomment debug flags ...
-
-From terminal run:
-
-```
-# Go to package folder
-R_HOME="/Library/Frameworks/R.framework/Resources"
-R_BIN="$R_HOME/bin/exec/R"
-ASAN="/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib/clang/17/lib/darwin/libclang_rt.asan_osx_dynamic.dylib"
-UBSAN="/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib/clang/17/lib/darwin/libclang_rt.ubsan_osx_dynamic.dylib"
-
-env R_HOME="$R_HOME" \
-  DYLD_INSERT_LIBRARIES="$ASAN:$UBSAN" \
-  ASAN_OPTIONS="abort_on_error=1,detect_leaks=0,verbosity=1" \
-  UBSAN_OPTIONS="print_stacktrace=1" \
-  "$R_BIN" --vanilla
-```
-
-In the R session (not from Rstudio/Positron!):
-
-```
-# Load + compile into the current ASan session (no child R load)
-devtools::load_all()
-
-# Run tests in the same process
-devtools::test()
-```
-
 ### Air formatter of R code
 
 https://usethis.r-lib.org/reference/use_air.html
@@ -264,13 +234,21 @@ pre-commit run clang-format --all-files
 
 https://clang.llvm.org/extra/clang-tidy/
 
+The repo uses two `clang-tidy` profiles:
+
+* `.clang-tidy`: stable low-noise pre-commit gate focused on correctness,
+  numerics, and a few performance checks.
+* `tools/clang_tidy_audit.yaml`: broader manual audit profile for occasional
+  sweeps; do not require this profile to be warning-free on every commit.
+
 ```
 echo $(brew --prefix llvm)/bin/clang-tidy
 # /opt/homebrew/opt/llvm/bin/clang-tidy
 export CLANG_TIDY="$(brew --prefix llvm)/bin/clang-tidy"
 ./tools/clang_tidy.py src/RcppTskit.cpp
 ./RcppTskit/tools/clang_tidy.py RcppTskit/src/test_tsk_abort_stderr.cpp -- -system-headers '-header-filter=.*'   -extra-arg=-Wno-unknown-warning-option
 ./tools/clang_tidy.py src/test_tsk_abort_stderr.cpp -- -system-headers '-header-filter=.*'   -extra-arg=-Wno-unknown-warning-option
+./tools/clang_tidy.py src/RcppTskit.cpp -- --config-file=tools/clang_tidy_audit.yaml
 ```
 
 or
@@ -280,6 +258,36 @@ pre-commit run clang-tidy src/RcppTskit.cpp
 pre-commit run clang-tidy --all-files
 ```
 
+### Debugging C/C++
+
+In `src/Makevars.in` uncomment debug flags ...
+
+From terminal run:
+
+```
+# Go to package folder
+R_HOME="/Library/Frameworks/R.framework/Resources"
+R_BIN="$R_HOME/bin/exec/R"
+ASAN="/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib/clang/17/lib/darwin/libclang_rt.asan_osx_dynamic.dylib"
+UBSAN="/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib/clang/17/lib/darwin/libclang_rt.ubsan_osx_dynamic.dylib"
+
+env R_HOME="$R_HOME" \
+  DYLD_INSERT_LIBRARIES="$ASAN:$UBSAN" \
+  ASAN_OPTIONS="abort_on_error=1,detect_leaks=0,verbosity=1" \
+  UBSAN_OPTIONS="print_stacktrace=1" \
+  "$R_BIN" --vanilla
+```
+
+In the R session (not from Rstudio/Positron!):
+
+```
+# Load + compile into the current ASan session (no child R load)
+devtools::load_all()
+
+# Run tests in the same process
+devtools::test()
+```
+
 ### GitHub actions
 
 ```