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/scripts/quality/README.md
+++ b/scripts/quality/README.md
@@ -23,6 +23,8 @@ consistency + markdown links + end-to-end smoke via `try_it.sh`).
 | `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)
--- a/scripts/quality/cgal-version-matrix.sh
+++ b/scripts/quality/cgal-version-matrix.sh
@@ -73,7 +73,11 @@ echo "  versions tested:"
 echo "$AVAILABLE" | sed 's/^/    /'
 echo "========================================"

-overall=0
+# Failures are recorded in $ROOT/.cgal-matrix-failures because the
+# while-loop runs in a subshell (consequence of the pipe from echo), so
+# a plain `overall=0; overall=1` would not survive back to the parent.
+rm -f "$ROOT/.cgal-matrix-failures"
+
 echo "$AVAILABLE" | while IFS= read -r cgal_root; do
    [ -z "$cgal_root" ] && continue
    ver="$(basename "$cgal_root")"
--- a/scripts/quality/clang-format.sh
+++ b/scripts/quality/clang-format.sh
@@ -23,7 +23,7 @@

 set -uo pipefail
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
-cd "$ROOT"
+cd "$ROOT" || exit 2

 command -v clang-format >/dev/null 2>&1 || {
    echo "FAIL: clang-format not in PATH." >&2
--- a/scripts/quality/clang-tidy.sh
+++ b/scripts/quality/clang-tidy.sh
@@ -40,20 +40,39 @@ TARGET_DIR="${1:-code/include}"
 [ -d "$TARGET_DIR" ] || { echo "FAIL: $TARGET_DIR is not a directory" >&2; exit 2; }

 # Generate compile_commands.json (clang-tidy needs it for include paths).
+# Enable WITH_CGAL_TESTS so the CGAL include directories are part of at
+# least one compile entry — clang-tidy walks those when linting headers
+# that don't appear in compile_commands.json directly.
 cmake -S code -B "$BUILD_DIR" \
    -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \
+    -DWITH_CGAL_TESTS=ON \
    -DCMAKE_BUILD_TYPE=Release \
    -Wno-dev >/dev/null

+# ── macOS workaround: brew-installed clang-tidy doesn't know where the
+# Apple Command-Line-Tools SDK lives, so it can't find <cmath>, <complex>,
+# <CGAL/...>, etc.  Pass `--extra-arg=-isysroot ...` to teach it.
+EXTRA_ARGS=()
+if [ "$(uname -s)" = "Darwin" ]; then
+    SDK="$(xcrun --show-sdk-path 2>/dev/null || true)"
+    if [ -n "$SDK" ]; then
+        EXTRA_ARGS+=(--extra-arg=-isysroot --extra-arg="$SDK")
+    fi
+fi
+
 mkdir -p "$BUILD_DIR"
 : > "$LOG"

-# Find every .h / .hpp under TARGET_DIR (skip deps + macOS dup files).
+# Find every .h / .hpp under TARGET_DIR (skip deps + macOS dup files +
+# viewer-only headers — those need `-DWITH_VIEWER=ON` plus a system
+# GLFW/libigl that we don't drag into the lint build).
 HEADERS=$(find "$TARGET_DIR" \
    \( -name "*.h" -o -name "*.hpp" \) \
    -type f \
    | grep -v "code/deps/" \
    | grep -v " 2\." \
+    | grep -v "viewer_utils\.h$" \
+    | grep -v "mesh_utils\.hpp$" \
    | sort)

 echo "========================================"
@@ -72,6 +91,7 @@ for h in $HEADERS; do
    # generated" boilerplate.  Pipe through tee for the log file.
    clang-tidy --quiet \
        -p "$BUILD_DIR" \
+        "${EXTRA_ARGS[@]}" \
        "$h" 2>&1 | tee -a "$LOG" || true
 done

--- a/scripts/quality/cmake-format.sh
+++ b/scripts/quality/cmake-format.sh
@@ -19,7 +19,7 @@

 set -uo pipefail
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
-cd "$ROOT"
+cd "$ROOT" || exit 2

 # Allow ~/.local/bin (pip-installed tools) in PATH.
 export PATH="$HOME/.local/bin:$PATH"
--- a/scripts/quality/codespell.sh
+++ b/scripts/quality/codespell.sh
@@ -24,7 +24,7 @@

 set -uo pipefail
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
-cd "$ROOT"
+cd "$ROOT" || exit 2

 command -v codespell >/dev/null 2>&1 || {
    echo "FAIL: codespell not in PATH." >&2
--- a/scripts/quality/cppcheck.sh
+++ b/scripts/quality/cppcheck.sh
@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+# scripts/quality/cppcheck.sh
+#
+# Run cppcheck over the public headers.  Complementary to clang-tidy:
+# cppcheck has different heuristics, fewer false-positives on heavy
+# template code (CGAL/Eigen), and catches some bugs (unused includes,
+# memory leaks in detail/) that clang-tidy is bad at.
+#
+# Local-only.  Promotion to CI when the existing tree is finding-free
+# at the chosen severity level.
+#
+# Usage:
+#   bash scripts/quality/cppcheck.sh           # error+warning only
+#   bash scripts/quality/cppcheck.sh --strict  # +style, exit 1 on any
+#   bash scripts/quality/cppcheck.sh --all     # absolute everything,
+#                                                useful for diffs only
+#
+# Exit codes:
+#   0  no findings at the chosen severity, or findings but not --strict
+#   1  findings + --strict
+#   2  prerequisite missing
+
+set -uo pipefail
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+cd "$ROOT" || exit 2
+
+command -v cppcheck >/dev/null 2>&1 || {
+    echo "FAIL: cppcheck not in PATH." >&2
+    echo "        macOS: brew install cppcheck" >&2
+    echo "        Linux: sudo apt install cppcheck" >&2
+    exit 2
+}
+
+STRICT=0
+ALL=0
+for arg in "$@"; do
+    case "$arg" in
+        --strict) STRICT=1 ;;
+        --all)    ALL=1 ;;
+        *) echo "Unknown arg: $arg" >&2; exit 2 ;;
+    esac
+done
+
+ENABLE="warning"
+if [ "$STRICT" -eq 1 ]; then ENABLE="warning,style"; fi
+if [ "$ALL"    -eq 1 ]; then ENABLE="all"; fi
+
+BUILD_DIR="build-cppcheck"
+LOG="$BUILD_DIR/cppcheck.log"
+mkdir -p "$BUILD_DIR"
+
+echo "cppcheck ($(cppcheck --version 2>&1 | head -1))"
+echo "  enable:  $ENABLE"
+echo "  log:     $LOG"
+echo
+
+# Suppress noise classes that are not actionable in our project:
+#   missingIncludeSystem — CGAL/Eigen/Boost headers are intentionally
+#                          included implicitly; cppcheck cannot resolve.
+#   unmatchedSuppression — cosmetic.
+#   unusedFunction       — header-only; many `inline` helpers ARE used,
+#                          cppcheck can't see across TUs.
+#   normalCheckLevelMaxBranches — informational, not a finding.
+#
+# We point cppcheck at code/include/ only.  The deps tree is third-party
+# code and out of scope.
+
+cppcheck \
+    --enable="$ENABLE" \
+    --std=c++17 \
+    --quiet \
+    --error-exitcode=2 \
+    --inline-suppr \
+    --suppress=missingIncludeSystem \
+    --suppress=unmatchedSuppression \
+    --suppress=unusedFunction \
+    --suppress=normalCheckLevelMaxBranches \
+    -I code/include \
+    code/include 2>&1 | tee "$LOG"
+rc=$?
+
+echo
+echo "── Summary ──"
+n=$(grep -cE "\[(error|warning|style|performance|portability)\]" "$LOG" || true)
+echo "  total findings: $n"
+echo "  full log:       $LOG"
+
+if [ "$STRICT" -eq 1 ] && [ "$n" -gt 0 ]; then
+    exit 1
+fi
+if [ "$rc" -eq 2 ] && [ "$STRICT" -ne 1 ]; then
+    # cppcheck signalled "error" severity but caller didn't ask --strict.
+    echo
+    echo "NOTE: cppcheck reported an `error`-severity finding.  Even"
+    echo "      without --strict, please review the log."
+fi
+exit 0
--- a/scripts/quality/run-all.sh
+++ b/scripts/quality/run-all.sh
@@ -28,7 +28,7 @@

 set -uo pipefail
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
-cd "$ROOT"
+cd "$ROOT" || exit 2

 FAST=0
 [ "${1:-}" = "--fast" ] && FAST=1
@@ -39,6 +39,8 @@ GATES_FAST=(
    "clang-format drift  | bash scripts/quality/clang-format.sh"
    "cmake-format/-lint  | bash scripts/quality/cmake-format.sh"
    "codespell           | bash scripts/quality/codespell.sh"
+    "shellcheck          | bash scripts/quality/shellcheck.sh"
+    "cppcheck            | bash scripts/quality/cppcheck.sh"
    "Markdown links      | python3 scripts/check-markdown-links.py"
    "Sanitizers          | bash scripts/quality/sanitizers.sh"
    "clang-tidy          | bash scripts/quality/clang-tidy.sh"
@@ -67,6 +69,7 @@ echo "============================================================"

 results=""
 failed=0
+skipped=0
 i=0
 for entry in "${GATES[@]}"; do
    i=$((i + 1))
@@ -79,12 +82,21 @@ for entry in "${GATES[@]}"; do
    log="$LOG_DIR/$slug.log"
    echo
    echo "──── [$i/${#GATES[@]}] $name  ────"
-    if eval "$cmd" >"$log" 2>&1; then
+    eval "$cmd" >"$log" 2>&1
+    rc=$?
+    # Exit code 2 from any of our gate scripts = "tool not installed".
+    # Treat as SKIP rather than FAIL so a partial dev environment can
+    # still run the rest of the sweep.
+    if [ "$rc" -eq 2 ] && head -3 "$log" | grep -qE "FAIL:.*not (in PATH|installed|found)"; then
+        echo "    SKIP   (tool not installed — see $log)"
+        results="${results}  SKIP  $name  (missing tool)
+"
+        skipped=$((skipped + 1))
+    elif [ "$rc" -eq 0 ]; then
        echo "    OK     ($log)"
        results="${results}  PASS  $name
 "
    else
-        rc=$?
        echo "    FAIL (rc=$rc) — see $log"
        echo "    last 20 lines:"
        tail -20 "$log" | sed 's/^/      /'
@@ -100,5 +112,7 @@ echo "  Summary"
 echo "============================================================"
 printf "%s" "$results"
 echo
-echo "  failed: $failed / ${#GATES[@]}"
+echo "  passed:  $((${#GATES[@]} - failed - skipped)) / ${#GATES[@]}"
+echo "  skipped: $skipped     (tool not installed; gate is local-only)"
+echo "  failed:  $failed"
 exit $failed
--- a/scripts/quality/sanitizers.sh
+++ b/scripts/quality/sanitizers.sh
@@ -57,11 +57,18 @@ echo "Using CXX = $CXX_BIN ($("$CXX_BIN" --version | head -1))"
 echo

 # ── Configure ────────────────────────────────────────────────────────────────
+# CMAKE_GTEST_DISCOVER_TESTS_DISCOVERY_MODE=PRE_TEST: without this,
+# gtest_discover_tests runs the (sanitizer-instrumented) test binary at
+# *build* time to enumerate test cases.  ASan aborts that subprocess
+# the moment it sees any allocation in static-init, which fails the
+# build before we can even get to ctest.  PRE_TEST defers discovery to
+# `ctest` invocation, which is exactly what we want.
 cmake -S code -B "$BUILD_DIR" \
    -DCMAKE_CXX_COMPILER="$CXX_BIN" \
    -DCMAKE_CXX_FLAGS="$SAN_FLAGS" \
    -DCMAKE_EXE_LINKER_FLAGS="$SAN_FLAGS" \
    -DCMAKE_BUILD_TYPE=Debug \
+    -DCMAKE_GTEST_DISCOVER_TESTS_DISCOVERY_MODE=PRE_TEST \
    -Wno-dev

 # ── Build the fast (non-CGAL) tests only ────────────────────────────────────
--- a/scripts/quality/shellcheck.sh
+++ b/scripts/quality/shellcheck.sh
@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# scripts/quality/shellcheck.sh
+#
+# Run shellcheck across every Bash script we own (scripts/**/*.sh).
+# Skips the macOS duplicate artefacts (` 2.sh`).
+#
+# Local-only.  CI promotion once every script is shellcheck-clean.
+#
+# Usage:
+#   bash scripts/quality/shellcheck.sh             # warn + advisory exit 0
+#   bash scripts/quality/shellcheck.sh --strict    # fail on any finding
+#
+# Exit codes:
+#   0  no findings, or findings but --strict not set
+#   1  --strict was set and shellcheck reported findings
+#   2  prerequisite missing
+
+set -uo pipefail
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+cd "$ROOT" || exit 2
+
+command -v shellcheck >/dev/null 2>&1 || {
+    echo "FAIL: shellcheck not in PATH." >&2
+    echo "        macOS: brew install shellcheck" >&2
+    echo "        Linux: sudo apt install shellcheck" >&2
+    exit 2
+}
+
+STRICT=0
+for arg in "$@"; do
+    case "$arg" in
+        --strict) STRICT=1 ;;
+        *) echo "Unknown arg: $arg" >&2; exit 2 ;;
+    esac
+done
+
+FILES="$(find scripts -name "*.sh" -type f 2>/dev/null \
+    | grep -v " 2\.sh" \
+    | sort)"
+
+if [ -z "$FILES" ]; then
+    echo "FAIL: no shell scripts found under scripts/" >&2
+    exit 2
+fi
+
+echo "shellcheck ($(shellcheck --version | sed -n '2p'))"
+echo "Scanning shell scripts under scripts/"
+echo
+
+n_total=0
+n_with_findings=0
+total_findings=0
+while IFS= read -r f; do
+    [ -z "$f" ] && continue
+    n_total=$((n_total + 1))
+    # -S style: warnings + above (skip "info" and "style" noise).
+    out="$(shellcheck --severity=warning --shell=bash "$f" 2>&1)"
+    if [ -n "$out" ]; then
+        echo "── $f ──"
+        echo "$out"
+        echo
+        n_with_findings=$((n_with_findings + 1))
+        # rough count: one finding per "In <file> line N:" block
+        cnt=$(printf '%s' "$out" | grep -c "^In .* line")
+        total_findings=$((total_findings + cnt))
+    fi
+done <<EOF
+$FILES
+EOF
+
+echo "── Summary ──"
+echo "  scripts scanned:      $n_total"
+echo "  scripts with issues:  $n_with_findings"
+echo "  total findings:       $total_findings"
+
+if [ "$STRICT" -eq 1 ] && [ "$total_findings" -gt 0 ]; then
+    exit 1
+fi
+exit 0