Merge pull request 'ci+quality: structural gates (CI: 3 new; local: 7 new + .clang-tidy)' (#18) from ci/structural-tests into main

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.

doc/architecture/locked-vs-flexible.md

@@ -262,7 +262,11 @@ mechanical next step rather than a missing piece of theory.
 | **Named-parameter chaining: `\|`-operator only, no `.a().b().c()`.** Member-style chaining would need a patch to CGAL's upstream `parameters_interface.h`, which we treat as a read-only vendored dependency.  The pipe operator is documented, ADL-discoverable, and equivalent in expressive power. | pipe shipped, member-chain deferred until upstream extension point exists | ~2 days (only if upstream PR is accepted) |
 | **Phase 9b-analytic: derivation complete, code uses block-FD.** The Schläfli-based analytic HyperIdeal Hessian is fully derived in [`hyperideal-hessian-derivation.md`](../math/hyperideal-hessian-derivation.md) (805 lines, all sign pitfalls covered).  The shipped code still uses per-face block-FD (already 96× faster than the legacy full-FD path). | research-ready writeup; implementation gated on the reviewer's view of whether the additional ~6× is worth it | ~2 weeks |
 | **Doxygen `WARN_IF_UNDOCUMENTED = NO`.** With `EXTRACT_ALL = YES`, every symbol is in the generated HTML — live at <https://tmoussa.codeberg.page/ConformalLabpp/> (auto-published from `main` by `.gitea/workflows/doxygen-pages.yml`) — but symbols without explicit doc comments show only their signature.  Public API surface (entry functions, named-parameter helpers, traits typedefs) has hand-written Doxygen; internal helpers vary. | clean (0 warnings) under current policy; not yet enforced "no undocumented symbol"; pursued on a separate branch | ~3 days to drive `WARN_IF_UNDOCUMENTED = YES` to zero |
-| **`check-test-counts.sh` not wired into CI.** The script exists, runs locally, and gives the correct answer (23 + 234 = 257 / 0 skipped).  CI does not yet fail on a mismatch. | local guard exists, CI integration pending next workflow touch | ~1 hour |
+| **`check-test-counts.sh` not wired into CI.** ✅ Closed by branch `ci/structural-tests`.  Step is now part of `.gitea/workflows/cpp-tests.yml` (re-uses the just-built `build/` dir; ~5 s overhead). | gate active on every PR | done |
+| **End-to-end smoke (`try_it.sh`) not in CI.** ✅ Closed by `ci/structural-tests`.  Added as a step after the CGAL job. | gate active on every PR | done |
+| **Internal markdown link checker.** ✅ Closed by `ci/structural-tests`.  New `.gitea/workflows/markdown-links.yml` runs on every PR that touches a `*.md` file, plus a weekly cron for external link rot. | gate active on every PR + weekly | done |
+| **Local quality gates (sanitizers, coverage, clang-tidy, multi-compiler, CGAL-version-matrix, reproducible-build, license-headers).** Eight scripts under `scripts/quality/`, driven by `run-all.sh`.  Documented in `scripts/quality/README.md` with promotion-to-CI checklist. | local-only by design; promotion gated on policy text in release-policy.md | done as scripts; 60 SPDX headers missing in `code/include/` will be a follow-up |
+| **Code-style / convention gates (clang-format + CGAL-conventions checker).** ✅ Closed by `ci/structural-tests`. Adds `.clang-format` (project style mechanically captured) + `clang-format.sh` (drift detector, `--fix` mode); `cgal-conventions.py` enforces 6 CGAL-specific idioms (include-guard format, `\file` brief, namespace nesting, named-parameter tag `_t` suffix, no `using namespace`, no stray `#define`).  Both are intentionally local-only — promotion to CI once the existing tree passes `--strict` (today CGAL-conventions does pass: 0/6 violations across 6 CGAL public headers; clang-format drift TBD pending toolchain install). | done as scripts; promotion deferred | done |
 | **CP-Euclidean and Inversive-Distance research-track entries.** Both ship a working DCE solver, but lack the auxiliary utilities the Euclidean / HyperIdeal entries have (curvature inspection helpers, edge-flip Delaunay maintenance for ID).  Out of port scope; listed in [`research-track.md`](../roadmap/research-track.md). | research-track, not blocking | per-utility |
 | **`StereographicUnwrapper`, `CircleDomainUnwrapper`, `CuttingUtility`, `KoebePolyhedron`.** Mentioned in roadmap + research-track docs but not yet ported.  Java versions still authoritative. | documented as Phase 11+ / optional | weeks each — explicit "out of port scope unless requested" |