test(e2e): #256 clang module operator-template canary + module-package hazard docs

mcpp has no defect here: --precompile succeeds and the crash is inside the
Clang frontend on the import side. But mcpp bundles LLVM, so the hazard ships
with the toolchain, and it lands squarely on the module-package pattern this
project recommends — wrapping an upstream header whose operators are static
inline templates and mirroring their signatures with a trivially-true
constraint is exactly how you hit it.

Two things it needs, both of which mcpp owns:

Documentation, so the next person does not repeat the bisect: every template
parameter of an exported operator template should be pinned by the FIRST
argument; otherwise deduce whole operand types and constrain them. The
reporter's shipped workaround is included, along with the property that makes
this so hard to attribute — the crash is name-keyed, so one poisoned
operator* makes every `x * y` in every importer crash on unrelated types.

A canary, because the alternative is finding out by accident. It is a STATE
canary rather than a pass/fail contract: the expectation table records
crash for LLVM 20-22 and ok for 18-19, and the test fails when reality stops
matching — a Clang bump that FIXES this is just as much a signal as one that
re-breaks it, and neither should be able to change what packages can express
without anyone noticing. A control build without the unpinned overload guards
the canary itself.

Verified against both bundled toolchains (20.1.7 and 22.1.8 crash as
recorded; system clang 18.1.3 and gcc 16.1.0 compile the same repro fine).
An upstream LLVM report is filed separately; this does not wait on it.

Author: Sunrisepeak

docs/03-toolchains.md

@@ -267,3 +267,56 @@ When `MCPP_HOME` is not set explicitly, mcpp locates the sandbox automatically b
 ## ABI Capability Enforcement
 
 A dependency can declare an `abi:<name>` capability (for example, `compat.glfw` declares `abi:glibc`). When the resolved toolchain's ABI does not satisfy any dependency's abi requirement, the build **fails early** with a suggested fix (for example, a musl-static toolchain encountering an abi:glibc dependency), replacing deeper link/header errors. Inspect with: `mcpp why toolchain`.
+
+## Known Toolchain Hazard: Operator Templates in Module Interfaces (Clang 20+)
+
+A module that exports **replacement operator templates** can poison name
+lookup for that operator in every importer when compiled by Clang 20 or 22:
+any translation unit that `import`s the module and uses that operator — **on
+any type at all** — crashes the frontend (SIGSEGV). GCC 16 and Clang 18 are
+unaffected, so this is a regression somewhere between Clang 18 and 20.
+
+This bites the module-package pattern directly. Wrapping an upstream header
+whose operators are `static inline` templates, and mirroring their signatures
+with a trivially-true constraint (the standard mixed-TU subsumption recipe),
+is exactly how you hit it.
+
+**The rule of thumb:** every template parameter should be pinned by the
+**first** function argument. Shapes that break this are the poisonous ones:
+
+```cpp
+// Poisonous — `n` and `l` are not determined by argument 1
+template<typename T, int m, int n, int l>
+Matx<T, m, n> operator*(const Matx<T, m, l>& a, const Matx<T, l, n>& b);
+
+// Poisonous — second typename appears only in argument 2
+template<typename T1, typename T2, int n>
+Vec<T1, n>& operator+=(Vec<T1, n>& a, const Vec<T2, n>& b);
+
+// Fine — every parameter is pinned by argument 1
+template<typename T, int m, int n>
+Matx<T, m, n> operator+(const Matx<T, m, n>& a, const Matx<T, m, n>& b);
+```
+
+The crash is **name-keyed**: one poisoned `operator*` declaration makes every
+`x * y` in every importer crash, for entirely unrelated types. The function
+body is irrelevant.
+
+**The workaround** is to deduce whole operand types and constrain them,
+rather than destructuring them in the parameter list. It stays
+call-compatible, and mixed-TU semantics survive because the upstream
+exact-pattern `static inline` remains more specialized and still wins there:
+
+```cpp
+template<typename MA, typename MB>
+    requires pick<typename MA::value_type>
+          && __is_same(MA, typename MA::mat_type)
+          && __is_same(MB, Matx<typename MB::value_type,
+                               (int)MA::rows, (int)MA::cols>)
+inline MA& operator+=(MA& a, const MB& b);
+```
+
+Tracked as [mcpp#256](https://github.com/mcpp-community/mcpp/issues/256).
+`tests/e2e/150_clang_module_operator_template.sh` is a canary over the
+bundled LLVM toolchains, so a future Clang bump that fixes — or re-breaks —
+this becomes visible instead of silently changing what packages can express.

tests/e2e/150_clang_module_operator_template.sh

@@ -0,0 +1,129 @@
+#!/usr/bin/env bash
+# #256: known-issue canary for a Clang regression that mcpp cannot fix but
+# that silently limits what a module package may export.
+#
+# A module exporting replacement operator templates whose parameters are NOT
+# all pinned by the first argument poisons name lookup for that operator in
+# every importer: the frontend SIGSEGVs on any use of the name, on any type.
+# Clang 18 and GCC 16 are fine; Clang 20 and 22 crash. Since mcpp bundles
+# LLVM, the hazard ships with the toolchain.
+#
+# This is a STATE canary, not a pass/fail contract: today the expected result
+# for the bundled toolchains is "crashes". The test fails when reality stops
+# matching the recorded expectation — i.e. when a Clang bump fixes it (time
+# to update the docs and the table) or when a version previously known-good
+# regresses. Silence here would mean a future toolchain bump quietly changed
+# what packages can express.
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$SCRIPT_DIR/_llvm_env.sh"
+
+if [[ ! -d "$LLVM_ROOT" ]]; then
+    echo "SKIP: no llvm payload installed"
+    exit 0
+fi
+
+CLANGXX="$LLVM_ROOT/bin/clang++"
+[[ -x "$CLANGXX" ]] || { echo "SKIP: no clang++ in $LLVM_ROOT"; exit 0; }
+
+TMP=$(mktemp -d)
+trap "rm -rf $TMP" EXIT
+cd "$TMP"
+
+cat > matx.h <<'EOF'
+#pragma once
+namespace cv {
+template<typename T, int m, int n> struct Matx {
+    T val[m*n];
+    typedef Matx<T, m, n> mat_type;
+    enum { rows = m, cols = n };
+};
+template<typename T> struct Point_ { T x, y; };
+using Point = Point_<int>;
+template<typename T, int m, int n, int l> static inline
+Matx<T, m, n> operator*(const Matx<T, m, l>& a, const Matx<T, l, n>& b) { return Matx<T,m,n>{}; }
+template<typename T> static inline
+Point_<T> operator*(const Point_<T>& a, int b) { return Point_<T>{a.x*b, a.y*b}; }
+}
+EOF
+
+# The module layer: upstream shape mirrored with a trivially-true constraint.
+# The 4-parameter Matx*Matx overload is the poisonous one — `n` and `l` are
+# not determined by the first argument.
+cat > m.cppm <<'EOF'
+module;
+#include "matx.h"
+export module m;
+export namespace cv {
+using cv::Matx;
+using cv::Point_;
+using cv::Point;
+inline namespace repl {
+template<typename T> inline constexpr bool pick = true;
+template<typename T, int m, int n, int l> requires pick<T> inline
+Matx<T, m, n> operator*(const Matx<T, m, l>& a, const Matx<T, l, n>& b) { return Matx<T,m,n>{}; }
+template<typename T> requires pick<T> inline
+Point_<T> operator*(const Point_<T>& a, int b) { return Point_<T>{a.x*b, a.y*b}; }
+}
+}
+EOF
+
+# Note: only a Point is multiplied. The crash is name-keyed, so an unrelated
+# type is enough — that is what makes the hazard so hard to attribute.
+cat > use.cpp <<'EOF'
+import m;
+int main() { cv::Point p{1,2}; auto q = p * 2; return q.x; }
+EOF
+
+"$CLANGXX" -std=c++23 --precompile m.cppm -o m.pcm > precompile.log 2>&1 || {
+    cat precompile.log
+    echo "FAIL: producing the BMI should always succeed — the defect is on the import side"
+    exit 1
+}
+
+set +e
+"$CLANGXX" -std=c++23 -fprebuilt-module-path=. -c use.cpp -o use.o > use.log 2>&1
+IMPORT_RC=$?
+set -e
+
+# Control: the same module WITHOUT the unpinned overload must always compile.
+# If this ever fails, the canary itself is broken rather than the toolchain.
+grep -v 'Matx<T, m, n> operator\*(const Matx<T, m, l>& a' m.cppm \
+    | grep -v 'template<typename T, int m, int n, int l> requires pick<T> inline' > ctl.cppm
+"$CLANGXX" -std=c++23 --precompile ctl.cppm -o ctl.pcm > ctl_pre.log 2>&1 || {
+    cat ctl_pre.log; echo "FAIL: control module failed to precompile"; exit 1; }
+
+# Recorded expectations, by LLVM major version.
+case "${LLVM_VERSION%%.*}" in
+    18|19) EXPECTED=ok ;;
+    20|21|22) EXPECTED=crash ;;
+    *) EXPECTED=unknown ;;
+esac
+
+if [[ $IMPORT_RC -eq 0 ]]; then ACTUAL=ok; else ACTUAL=crash; fi
+
+echo "  llvm@${LLVM_VERSION}: expected=${EXPECTED} actual=${ACTUAL}"
+
+if [[ "$EXPECTED" == "unknown" ]]; then
+    echo "  no recorded expectation for LLVM ${LLVM_VERSION%%.*} — record one in this test"
+    echo "OK"
+    exit 0
+fi
+
+if [[ "$ACTUAL" != "$EXPECTED" ]]; then
+    echo
+    echo "FAIL: #256 canary state changed for llvm@${LLVM_VERSION}."
+    if [[ "$ACTUAL" == "ok" ]]; then
+        echo "  The importer now compiles — the Clang regression appears FIXED."
+        echo "  Update the expectation table here and the hazard section in"
+        echo "  docs/03-toolchains.md, and tell mcpp-community/mcpp#256."
+    else
+        echo "  The importer now crashes on a version previously known good."
+        echo "  A toolchain bump has re-broken module operator templates."
+        sed -n '1,25p' use.log
+    fi
+    exit 1
+fi
+
+echo "OK"