quality: 4 more gates + dependency audit; full --fast sweep 10/10 green

This commit closes the structural-tests work on PR #18. Every gate in `run-all.sh --fast` now passes end-to-end on the canonical dev machine. New gates ───────── 1. shellcheck (scripts/quality/shellcheck.sh) * Scans every `scripts/**/*.sh` at severity=warning+ * 16 scripts inspected; cleanup pass took the tree from 7 findings (SC2164 + SC2034) to 0 findings. 2. cppcheck (scripts/quality/cppcheck.sh) * Complementary static analyser to clang-tidy; different heuristics, fewer false-positives on heavy CGAL/Eigen templates. * Default severity warning+, --strict adds style, --all = everything. * Suppresses 4 noise classes (missingIncludeSystem, etc.) explicitly. 3. .editorconfig * Cross-IDE fallback for editors that don't honour clang-format. * Covers Markdown (preserve trailing whitespace), Python, YAML, JSON, shell, Makefile (tabs) — the file types clang-format doesn't cover. 4. CONFORMALLAB_WARNINGS_AS_ERRORS CMake option * Off by default → regular builds don't break on new GCC warnings. * `-DCONFORMALLAB_WARNINGS_AS_ERRORS=ON` adds `-Werror`, intended for CI promotion-track and sanitizer runs. Dependency audit (doc/architecture/dependencies.md) ──────────────────────────────────────────────────── New single-source-of-truth document listing: * what the library requires (Eigen + CGAL + Boost — all header-only) * what tests require (auto-fetched GTest, no system install) * what each quality tool is for, install command per OS, and behaviour when missing (each gate exits 2 = SKIP, run-all recognises this and continues) * a verification recipe that strips PATH down and shows the library still configures + builds + tests cleanly with zero quality tools installed. run-all.sh enhanced ─────────────────── * Recognises "tool not in PATH" → SKIP (not FAIL). * Summary now reports `passed / skipped / failed` separately. Bug fixes uncovered by the sweep ──────────────────────────────── * sanitizers.sh: gtest_discover_tests ran the ASan-instrumented binary at build time and aborted → added `-DCMAKE_GTEST_DISCOVER_TESTS_DISCOVERY_MODE=PRE_TEST` to defer discovery to ctest invocation. Now 23/23 sanitizer-instrumented tests pass. * clang-tidy.sh on macOS: brew-installed clang-tidy couldn't find Apple SDK system headers (<cmath>, <complex>, …) → added `--extra-arg=-isysroot $(xcrun --show-sdk-path)` on Darwin. * clang-tidy.sh: needed `-DWITH_CGAL_TESTS=ON` in compile_commands generation so CGAL include paths are part of at least one compile entry. Now resolves CGAL/Surface_mesh.h etc. * clang-tidy.sh: viewer-only headers (`viewer_utils.h`, `mesh_utils.hpp`) excluded — they need `WITH_VIEWER=ON` + system GLFW/libigl that the lint build doesn't drag in. * `.codespellrc`: extended ignore list (recognise, signalled, modelled, travelled, …) for British-English consistency across own writing. Final state — local quality block on this commit, this branch: ✅ License headers (66/66 carry MIT SPDX) ✅ CGAL conventions (0/6 violations on 6 CGAL headers) ✅ clang-format drift (0 drift) ✅ cmake-format/-lint (0 drift, 0 lint findings) ✅ codespell (0 typos in scope) ✅ shellcheck (0 findings across 16 .sh files) ✅ cppcheck (warning+ severity clean) ✅ Markdown links (122/122 resolve) ✅ Sanitizers (ASan+UBSan) (23/23 fast tests pass) ✅ clang-tidy (35 headers inspected, 0 findings) Library standalone-ness verified: env -i PATH=... cmake -S code -B /tmp/build-standalone cmake --build /tmp/build-standalone --target conformallab_tests ctest -E '^cgal\.' → all green Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-24 09:56:40 +02:00
parent d3c08b3bc0
commit 1aa3493e7d
14 changed files with 463 additions and 10 deletions
--- a/doc/architecture/dependencies.md
+++ b/doc/architecture/dependencies.md
@@ -0,0 +1,151 @@
+# Dependencies & standalone-ness
+
+This document is the single source of truth for "what does conformallab++
+**require** vs. what does it **optionally** use".  Anyone evaluating the
+project for inclusion (CGAL submission, downstream consumer, Linux
+distribution package, reviewer audit) should be able to read this page
+and know exactly which dev tools are mandatory, which are nice-to-have,
+and which can be skipped or replaced.
+
+## TL;DR
+
+| Layer | What is required | What is optional |
+|---|---|---|
+| **Library use** (header-only, end-user code includes our headers) | C++17 compiler, CMake ≥ 3.20, Eigen ≥ 3.4 (headers), CGAL ≥ 5.6 (headers), Boost ≥ 1.74 (headers — needed by CGAL's BGL adapters) | — |
+| **Test build + run** | the above + GTest (auto-fetched by CMake `FetchContent`, no system install needed) | — |
+| **Documentation build** | Doxygen ≥ 1.10 | Graphviz (call graphs), MathJax (renders inline) |
+| **Local quality gates** (`scripts/quality/`) | nothing the library doesn't already need | every gate is **independent**; each one not installed is **skipped**, not failed |
+| **Optional viewer** (`-DWITH_VIEWER=ON`) | GLFW (vendored under `code/deps/glfw-3.4`), libigl, OpenGL system headers | — |
+
+The library itself is **header-only**.  There is no compiled `.so` /
+`.a` / `.lib` we ship; consumers just `#include` and let their build
+system do the rest.
+
+## Library deps (required to build/use the C++ headers)
+
+| Dep | Version | Header-only? | Purchase | Required by |
+|---|---|---|---|---|
+| **C++17 compiler** | g++ ≥ 11, clang++ ≥ 14, AppleClang ≥ 14 | n/a | system / brew / apt | everything |
+| **CMake** | ≥ 3.20 | n/a | system / brew / apt | build orchestration |
+| **Eigen** | ≥ 3.4 (header-only) | yes | system (`apt install libeigen3-dev`) or vendored under `code/deps/eigen-*/` | every functional & solver |
+| **CGAL** | ≥ 5.6 (header-only) | yes | system (`apt install libcgal-dev`) or downloaded tarball | `code/include/CGAL/*` wrappers + Surface_mesh |
+| **Boost** | ≥ 1.74 (header-only) | yes | system (`apt install libboost-dev`) | only when `WITH_CGAL_TESTS=ON` or `WITH_CGAL=ON`, because CGAL's BGL adapters pull in `boost::graph_traits` |
+| **GTest** | 1.14 | yes (auto-fetched) | `FetchContent_Declare` in `code/CMakeLists.txt` — never installed system-wide | tests only |
+
+Notes:
+- The library headers in `code/include/*.hpp` use only Eigen + STL.
+- The CGAL wrapper headers in `code/include/CGAL/*.h` add CGAL + Boost
+  (transitively).
+- `code/deps/single_includes/json.hpp` is the vendored
+  [nlohmann/json](https://github.com/nlohmann/json) header — used by
+  `serialization.hpp` only.  No system install needed.
+
+## Build modes — what each requires
+
+| Mode | CMake invocation | Extra system deps |
+|---|---|---|
+| **Fast / pure-math tests** (default) | `cmake -S code -B build` | none beyond C++17 + CMake |
+| **CGAL headless tests** | `cmake -S code -B build -DWITH_CGAL_TESTS=ON` | Boost headers |
+| **Full build** (CLI + viewer) | `cmake -S code -B build -DWITH_CGAL=ON` | Boost + Wayland/X11 dev headers |
+| **Coverage / sanitizers / etc.** | see `scripts/quality/` | per-script (each documents its prereqs and skips if missing) |
+
+The `-DWITH_*` flags **all default to OFF**.  A fresh checkout +
+`cmake -S code -B build` works with nothing but a C++17 compiler and
+CMake — useful for evaluating the math without taking on the full CGAL
+toolchain.
+
+## Local quality gates — all optional, each independently skippable
+
+`scripts/quality/` contains 12 gate scripts.  None of them is wired
+into the regular CMake build; each is a standalone shell or Python
+invocation.  When the underlying tool is not installed, the script
+exits with **code 2** and a clear message; `scripts/quality/run-all.sh`
+recognises this as **SKIP**, not FAIL.
+
+| Tool | Used by | Install (macOS) | Install (Debian/Ubuntu) | Behaviour if missing |
+|---|---|---|---|---|
+| `clang-format` ≥ 15 | `clang-format.sh` | `brew install clang-format` | `apt install clang-format` | gate prints install hint, exits 2 → SKIP |
+| `clang-tidy` ≥ 14 | `clang-tidy.sh` | `brew install llvm` (then PATH-prepend `$(brew --prefix llvm)/bin`) | `apt install clang-tidy` | SKIP |
+| `cmake-format` / `cmake-lint` | `cmake-format.sh` | `pip3 install --user cmakelang` + PATH-prepend `~/.local/bin` | `pip3 install --user cmakelang` | SKIP |
+| `codespell` | `codespell.sh` | `brew install codespell` | `apt install codespell` (or `pip3 install codespell`) | SKIP |
+| `shellcheck` | `shellcheck.sh` | `brew install shellcheck` | `apt install shellcheck` | SKIP |
+| `cppcheck` | `cppcheck.sh` | `brew install cppcheck` | `apt install cppcheck` | SKIP |
+| `lcov` (+ `gcov` from the compiler) | `coverage.sh` | `brew install lcov` | `apt install lcov` | SKIP |
+| second `g++` or `clang++` | `multi-compiler.sh` | `brew install gcc` or `brew install llvm` | `apt install g++` / `clang++-N` | runs against whatever compilers it finds; WARNING if < 2 |
+| extra CGAL source trees | `cgal-version-matrix.sh` | manually `git clone` under `~/cgal/<ver>/` (or pass `CGAL_ROOTS=...`) | same | exits 2 → SKIP with explicit recovery hint |
+
+### How to disable a gate temporarily
+
+Two options:
+
+1. **Don't install the tool** — `run-all.sh` skips it.
+2. **Remove the line from `GATES_FAST` / `GATES_SLOW` in `run-all.sh`** —
+   the script is a 5-line edit; no separate "disabled" flag system.
+
+There is no global "disable all quality gates" switch by design.  If
+the gates feel heavy, run only the fast subset (`run-all.sh --fast`,
+~5 seconds wall-time when all tools are present); if even that is too
+much, invoke the one gate you care about directly.
+
+### `CONFORMALLAB_WARNINGS_AS_ERRORS` — the only CMake-level quality flag
+
+By default the build adds `-Wall -Wextra -Wpedantic` but does **not**
+fail on warnings.  Set `-DCONFORMALLAB_WARNINGS_AS_ERRORS=ON` for a
+strict build (intended for CI promotion-track and for sanitizer runs).
+Defaulting to off keeps the build green on slightly-newer toolchains
+that may flag new warning classes we haven't yet annotated.
+
+## CI gates (active on every PR via `.gitea/workflows/`)
+
+These run inside the `git.eulernest.eu/conformallab/ci-cpp:latest`
+container, so the tools are baked into the image — contributors do not
+need any of them locally:
+
+| Gate | Workflow file |
+|---|---|
+| ctest (fast + CGAL suites) | `cpp-tests.yml` |
+| test-count consistency | same |
+| End-to-end `try_it.sh` | same |
+| Markdown link check | `markdown-links.yml` |
+| Doxygen build + Codeberg Pages publish | `doxygen-pages.yml` |
+| Mirror to Codeberg | `mirror-to-codeberg.yml` |
+
+The local quality gates under `scripts/quality/` are **not** in CI
+today.  Each one's promotion path is documented in
+`scripts/quality/README.md`.
+
+## Verification of the standalone claim
+
+Test recipe (any UNIX, ~30 s):
+
+```bash
+# Strip PATH down to system + brew core (no quality tools).
+env -i PATH="/usr/bin:/bin:/opt/homebrew/bin" HOME="$HOME" \
+    cmake -S code -B /tmp/build-standalone
+
+# Build the fast test suite.
+cmake --build /tmp/build-standalone --target conformallab_tests
+
+# Run them.
+ctest --test-dir /tmp/build-standalone -E "^cgal\."
+```
+
+If this passes, the library is genuinely independent of every quality
+tool listed above.  Tested locally on macOS-arm64 — green.
+
+For the CGAL-mode equivalent (adds Boost headers as a system dep):
+
+```bash
+env -i PATH="/usr/bin:/bin:/opt/homebrew/bin" HOME="$HOME" \
+    cmake -S code -B /tmp/build-cgal -DWITH_CGAL_TESTS=ON
+cmake --build /tmp/build-cgal --target conformallab_cgal_tests
+ctest --test-dir /tmp/build-cgal -R "^cgal\."
+```
+
+## What is **not** in this repo (out of scope)
+
+- No package-manager metadata (Debian `.deb`, RPM, Conan, vcpkg, …) —
+  yet.  Adding them is downstream work; the header-only nature makes
+  each trivial.
+- No language bindings (Python, …) — out of scope; the library is C++.
+- No GPU compute path — out of scope; numerical work is CPU-only.