5 Commits

Author	SHA1	Message	Date
Tarik Moussa	569a03dc08	docs+tooling: doc-freshness gate, documentation-pass policy, token-hygiene ... Refresh CLAUDE.md for v0.10.0 (3 CI jobs incl. disabled test-cgal, compile-time option matrix, reviewer/pages docs, agentic + token-hygiene workflow patterns) and condense the historical Phase-8/audit logs to pointers. Add the documentation-pass process so the single-source-of-truth rules stay enforced: * scripts/quality/check-doc-freshness.sh — string-only drift gate (version/date across CITATION/CHANGELOG/CLAUDE, doc-map count), <1 s, registered in run-all.sh + quality README. * doc/release-policy.md — "Documentation passes" subsection (triggers + docs:sync rule); fix stale Phase-milestone mapping (v0.10.0 was reviewer-ready, 9c→v0.11.0) and the test-cgal CI mention. Add shared Claude config (un-ignore the two files only): * .claude/settings.json — permission allowlist for safe repo commands. * .claude/token-hygiene.md — Tier-3 cache-discipline user guide that CLAUDE.md instructs Claude to remind the user about. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>	2026-05-28 06:15:14 +02:00
Tarik Moussa	1aa3493e7d	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
Tarik Moussa	d3c08b3bc0	quality: 2 new gates (cmake-format, codespell) + SPDX rollout (60 files) ... This commit closes the remaining red gates so `run-all.sh --fast` is green end-to-end on the canonical dev machine. New gates ───────── 1. cmake-format / cmake-lint * scripts/quality/cmake-format.sh — dry-run by default, --strict to fail on drift, --fix to apply * .cmake-format.yaml — policy (lowercase commands, UPPERCASE keywords, 100-col loose limit; matches .clang-format choices) * Uses the pip-installed `cmakelang` package (`pip3 install --user cmakelang`) 2. codespell * scripts/quality/codespell.sh — exit 1 on any typo, --fix interactively * .codespellrc — extensive ignore-words-list capturing the project's British-English-leaning style (centre, behaviour, specialise, normalise, …) plus domain abbreviations (DOF, iff, fuchsiens), so the gate flags real typos only. * Validated: 0 typos across docs + code/include + scripts + code/{src,tests}. SPDX rollout (license-headers --fix) ──────────────────────────────────── license-headers.sh gained a --fix mode that auto-inserts the two-line header at the correct place (below `#pragma once` if present, above the include guard otherwise, plain prepend for .cpp). Ran it on 60 of 66 files — 100 %-licensed now. Verified the build is still clean after the textual edits: cmake -S code -B build-verify -DWITH_CGAL_TESTS=ON ctest --test-dir build-verify → 257/257 PASS run-all.sh + README updated to include the two new gates. End-to-end style/convention block status (on this commit, this branch): ✅ license-headers (66/66 carry MIT SPDX) ✅ cgal-conventions (0/6 violations) ✅ clang-format (0 drift; warn-mode for safety) ✅ cmake-format/-lint (warn-mode for safety) ✅ codespell (0 typos) ✅ markdown-links (122/122 resolve) The slow correctness/quality block (sanitizers, coverage, clang-tidy, multi-compiler, cgal-version-matrix, reproducible-build) is left as follow-up — toolchain is now installed locally, scripts are syntax- clean, the slow runs themselves are a separate matter of patience. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>	2026-05-24 09:15:34 +02:00
Tarik Moussa	f1d77aa293	quality: add code-style + CGAL-convention checkers (local-only) ... Closes the gap "no code-quality / convention gate" from the structural review. Three new artefacts, all local-only (CI promotion deferred until the existing tree is 100 % clean under each): 1. .clang-format — project's existing style mechanically captured (4-space indent, opening brace on new line for class/struct/function, left-aligned pointer/reference modifiers, aligned `using = ...` blocks, 100-col loose limit, no include re-ordering — matches code/include/ today). 2. scripts/quality/clang-format.sh — drift detector. Dry-run mode by default (always exits 0); --strict to fail on drift; --fix to apply suggested changes in place. Skips code/deps/ and macOS-duplicate files. 3. scripts/quality/cgal-conventions.py — checker for the CGAL idioms that clang-format/clang-tidy cannot express: CGAL-1 include-guard format `CGAL_<DIRS>_<FILE>_H` CGAL-2 every public header has a `\\file` Doxygen brief CGAL-3 no nested namespaces beyond the allowed set (CGAL::parameters, CGAL::Conformal_map, internal_np, IO) CGAL-4 named-parameter tag types end in `_t`; value object does not CGAL-5 no `using namespace ...` at file scope (header leakage) CGAL-6 no #define beyond CGAL_* / include-guard Result on the current tree: 6 CGAL public headers, 0 violations. The checker therefore doubles as documentation of the conventions we already follow. Both are wired into scripts/quality/run-all.sh's fast subset (~5 s combined wall time). README.md updated to split the gates into a "style/convention" group (cheap, run-on-every-commit material) and a "correctness/quality" group (slow, run-before-tag material). The reviewer-facing locked-vs-flexible.md gains another "✅ Closed" row documenting both gates and the 0-violation baseline. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>	2026-05-24 08:37:12 +02:00
Tarik Moussa	a2eee9c279	ci+quality: structural gates (CI: 3 new; local: 7 new + .clang-tidy) ... CI gates (active on every PR via .gitea/workflows/) ─────────────────────────────────────────────────── 1. test-count consistency cpp-tests.yml gains a step after test-cgal that runs `scripts/check-test-counts.sh` against the just-built ./build dir (reuse via new BUILD_DIR env var, ~5 s overhead). Drift between `doc/api/tests.md` and ctest reality now fails the PR. 2. End-to-end smoke `scripts/try_it.sh` (the documented user quick-start) is now part of the CGAL job, so README quick-start regressions fail the PR rather than silently breaking when users land. 3. Internal markdown link checker New `.gitea/workflows/markdown-links.yml` + `scripts/check-markdown -links.py`. PRs that touch any *.md file run the check; main pushes trigger it too; a weekly cron catches external link rot. Pure Python, no third-party action. Validated against the current tree: 122 internal links across 37 *.md files, 0 broken. Local quality scripts (`scripts/quality/`, not in CI) ───────────────────────────────────────────────────── * `license-headers.sh` — `SPDX-License-Identifier: MIT` audit over code/{include,src,tests}/. Currently reports 60/66 files missing it — that's a follow-up; the script captures the structural gap. * `sanitizers.sh` — ASan + UBSan over the fast test suite. * `coverage.sh` — gcov/lcov line + branch coverage of code/include/, HTML report under build-coverage/lcov-html/. * `clang-tidy.sh` — runs the curated `.clang-tidy` policy over every public header. * `multi-compiler.sh` — sequential build + test against every detected g++/clang++ (auto-discovery or explicit list). * `cgal-version-matrix.sh`— sequential build + CGAL test suite against every CGAL tree under `~/cgal/<ver>/` (or via `CGAL_ROOTS=...` env var). * `reproducible-build.sh`— two `Release -j1` builds, fail if any test executable byte-differs. * `run-all.sh` — driver: `--fast` for the ~5-min subset, no arg for the ~25–40 min full sweep; captures per-gate logs to build-quality-logs/. + `.clang-tidy` — curated, deliberately-small policy (only checks that fire on OUR code, never on transitive CGAL/Eigen/Boost headers). + `scripts/quality/README.md` — explains the structure, lists each gate's wall-time + prereqs, and codifies the promotion path: a gate moves into CI only when it's green on the dev machine AND has a recovery-instructions paragraph in `doc/release-policy.md`. Doc updates ─────────── `doc/architecture/locked-vs-flexible.md` (reviewer-facing) gains 4 "closed" rows in the limitations table — the 3 CI gates above and the local quality-script suite. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>	2026-05-24 08:25:09 +02:00