ConformalLabpp/scripts/quality

Local structural quality gates

This directory contains the structural quality checks that run locally rather than in CI. They are intentionally not wired into .gitea/workflows/ (yet) because each is either too slow, too brittle against the runner environment, or both — running them before a release or before showing the repo to an external reviewer is the intended workflow.

The CI gates that are enforced live in .gitea/workflows/cpp-tests.yml and .gitea/workflows/doxygen-pages.yml; they cover the day-to-day correctness loop (build + test + doxygen-coverage + test-count consistency + markdown links + end-to-end smoke via try_it.sh).

What runs locally

Style / convention gates (run on every commit; cheap)

Script	What it checks	Wall time	Prereqs
license-headers.sh	every C++ source carries SPDX-License-Identifier: MIT	~1 s	bash
cgal-conventions.py	CGAL-1…6: include-guard format, \file brief, namespace nesting, tag-naming, no using namespace, no stray #define	~1 s	python3
clang-format.sh	every C++ source matches .clang-format (dry-run by default; --fix to apply)	~2 s	clang-format ≥ 15
cmake-format.sh	every CMakeLists.txt matches .cmake-format.yaml + passes cmake-lint	~2 s	cmake-format (pip: cmakelang)
codespell.sh	typo check across docs + source comments + script messages	~1 s	codespell
shellcheck.sh	static analysis of every scripts/**/*.sh	~1 s	shellcheck
cppcheck.sh	second-opinion static analyser over code/include/	~5 s	cppcheck
../check-markdown-links.py	every internal markdown link resolves	~2 s	python3

Correctness / quality gates (run before tagging or reviewer demos)

Script	What it checks	Wall time	Prereqs
sanitizers.sh	fast test suite under ASan + UBSan	~3 min	clang++ ≥ 14 or g++ ≥ 11
coverage.sh	gcov/lcov line + branch coverage of code/include/	~2 min	lcov
clang-tidy.sh	curated clang-tidy checks over public headers	~2 min	clang-tidy ≥ 14, .clang-tidy
multi-compiler.sh	build + test under every detected gcc/clang	~5 min × N compilers	any 2 of g++, clang++
reproducible-build.sh	two builds → byte-identical test executables	~6 min	none beyond compiler
cgal-version-matrix.sh	build + CGAL test suite against multiple CGAL versions	~5 min × N versions	CGAL trees under ~/cgal/<ver>/ (or CGAL_ROOTS=...)

How to use

# Fast subset (license + links + sanitizers + clang-tidy) — ~5 min total
bash scripts/quality/run-all.sh --fast

# Full sweep — ~25–40 min, intended for pre-release tagging
bash scripts/quality/run-all.sh

# One specific gate
bash scripts/quality/sanitizers.sh

Every gate writes its full output to build-quality-logs/<gate>.log when invoked via run-all.sh, and to its own per-gate build directory (build-sanitizers/, build-coverage/, build-multi-<cc>/, …) when invoked directly.

Promotion path to CI

Each gate can be wired into .gitea/workflows/cpp-tests.yml once two conditions are met:

1. The gate is green on the canonical dev machine. If the script exits 1 today, the CI gate would block every PR.
2. There is a published policy line in doc/release-policy.md that explains what regression the gate catches and what the recovery is. Future contributors should be able to read the error and know what to fix.

Promoting a gate is a one-line change to cpp-tests.yml; the test recipe is the script invocation itself.

Known limitations

• cgal-version-matrix.sh does not download CGAL. Each version must already be on the dev machine under ~/cgal/<ver>/ (override with CGAL_ROOTS=...:...). The Dockerfile under .gitea/docker/Dockerfile.ci-cpp could be extended to ship multiple CGAL trees in a single image; not done yet.
• sanitizers.sh only instruments the fast (non-CGAL) test suite — the CGAL templates are too expensive to compile under instrumentation on most laptops.
• clang-tidy.sh requires a .clang-tidy config in the repo root; the default Anthropic-quality lint set is intentionally minimal until the reviewer signs off on the warning policy.
• reproducible-build.sh checks the test executables only. The library is header-only, so there is nothing else to compare.