ci-target-matrix.yml

name: target matrix

# 让支持矩阵成为一次测量的输出,而不是一份会悄悄过期的文档。
#
# 这套东西存在的理由,是本仓库反复付出的一类代价:一格因为「今天这台机器恰好
# 装了某个载荷」而通过,或因为没装而跳过,而两者在退出码上与「全部正确」没有区别。
# 三个宿主各扫一遍,把结果与仓库里的期望表比对,差异即失败。
on:
  workflow_call:

env:
  XLINGS_NON_INTERACTIVE: '1'

jobs:
  invariants:
    # 第一层:四条恒等式,不需要期望表,也不依赖机器上装了什么。
    #    它们是结构约束 —— 任何一格只要跑起来了就该满足。
    name: invariants (${{ matrix.host }})
    runs-on: ${{ matrix.runner }}
    timeout-minutes: 90
    strategy:
      fail-fast: false
      matrix:
        include:
          # THE BUILD-HOST AXIS IS THE SET mcpp SHIPS FOR, NOT THE SET THAT
          # WAS CONVENIENT. `release.yml` publishes four: linux-x86_64,
          # linux-aarch64, macosx-arm64, windows-x86_64. A host mcpp is
          # distributed for and never scanned is a host whose target table is
          # a claim nobody checked.
          #
          # `host` IS (os, arch) AND NOT os. Two Linux hosts differ in which
          # rows they serve — `x86_64-linux-gnu` needs the host-native glibc
          # payload, so it is reachable on one and not the other — and a single
          # `linux` key would have them overwrite each other in expected.tsv.
          - { host: linux-x86_64,   runner: ubuntu-24.04     }
          - { host: linux-aarch64,  runner: ubuntu-24.04-arm }
          - { host: macos-arm64,    runner: macos-15         }
          - { host: windows-x86_64, runner: windows-2022     }
    defaults:
      run:
        shell: bash
    steps:
      - uses: actions/checkout@v4
      - uses: ./.github/actions/bootstrap-mcpp

      # This commit's mcpp: the one build.yml produced (use-built-mcpp, rule R1
      # of the 2026-10-02 CI record). Every leg runs on the image its artifact
      # was built on; the macOS leg moved to macos-15 when GitHub retired
      # macos-14 (2026-11-02), and with it the reason it built its own.
      - uses: ./.github/actions/use-built-mcpp
        with:
          host: ${{ matrix.host }}

      - name: Name this commit's mcpp MCPP_UNDER_TEST
        run: echo "MCPP_UNDER_TEST=$MCPP_FRESH" >> "$GITHUB_ENV"

      - name: The invariants
        run: |
          set -euo pipefail
          export MCPP="$MCPP_UNDER_TEST"
          export MCPP_VENDORED_XLINGS="$XLINGS_BIN"
          "$MCPP" self config --mirror GLOBAL 2>/dev/null || true
          # These four read mcpp's MACHINE interface, so jq is not optional
          # here. Without it each one takes its own "nothing to compare" exit —
          # four honest-looking skips, and the next step would then report that
          # the invariants did not run. Failing on the cause beats failing on
          # the symptom four steps later.
          command -v jq >/dev/null || { echo "::error::jq is missing on ${{ matrix.host }}"; exit 1; }
          fail=0
          for t in tests/e2e/295_*.sh tests/e2e/296_*.sh \
                   tests/e2e/297_*.sh tests/e2e/298_*.sh \
                   tests/e2e/299_*.sh tests/e2e/300_*.sh \
                   tests/e2e/301_*.sh tests/e2e/302_*.sh \
                   tests/e2e/303_*.sh; do
            echo "=== $t ==="
            bash "$t" 2>&1 | tee "$(basename "$t").log" || true
            rc=${PIPESTATUS[0]}
            [ "$rc" = "0" ] || { echo "::error::$t failed (exit $rc)"; fail=1; }
          done
          [ "$fail" = 0 ] || exit 1

      - name: Native ARM64 LLVM payload admission
        if: matrix.host == 'linux-aarch64'
        env:
          MCPP: ${{ env.MCPP_UNDER_TEST }}
          MCPP_VENDORED_XLINGS: ${{ env.XLINGS_BIN }}
        run: bash .github/tools/check_aarch64_llvm_payload.sh

      - uses: actions/upload-artifact@v4
        if: ${{ always() && matrix.host == 'linux-aarch64' }}
        with:
          name: native-llvm-arm64-admission
          path: ${{ runner.temp }}/native-llvm-arm64
          if-no-files-found: warn

      - name: Each invariant RAN
        run: |
          set -euo pipefail
          # 这一步存在的全部理由:退出码分不清「通过」与「跳过」。两条 e2e 都
          #    有为「这台机器没有可比的东西」准备的早退,而 CI 要的是它们真的比
          #    过了。
          check() {
            grep -qF "$2" "$1".log || {
              echo "::error::$1 did not reach its conclusion on ${{ matrix.host }}"
              tail -6 "$1".log 2>/dev/null | sed 's/^/        /'
              return 1
            }
            echo "  ok  $1"
          }
          # A SKIP IS ACCEPTED FOR ONE NAMED REASON, NOT ON ONE NAMED HOST.
          #
          # 297 declares a non-llvm compiler, so it needs one to exist. Every
          # toolchain mcpp installs on macOS is llvm; on windows-2022 it depends
          # on what the restored cache holds — measured, one run had
          # `gcc@16.1.0` and the next had only `llvm@20.1.7`.
          #
          # THE FIRST VERSION EXEMPTED macOS BY NAME, and the very next
          # Windows run skipped for the same reason and went red. Naming the
          # host encodes where the fact happened to hold; naming the FACT holds
          # wherever it does. A skip for any other reason is still a failure.
          #
          # AND THE DENOMINATOR IS ASSERTED SEPARATELY: linux always has a gcc
          # payload (it backs the host row), so that job uses `check` and the
          # test is guaranteed to be exercised somewhere on every run. Without
          # that, a reason accepted everywhere is a test that runs nowhere.
          check_or_declared_skip() {   # log  ok-line  acceptable-skip-pattern (ERE)
            grep -qF "$2" "$1".log && { echo "  ok  $1"; return 0; }
            if grep -q '^SKIP:' "$1".log && grep -qE "$3" "$1".log; then
              echo "  ok  $1 (declared skip: $(grep -m1 '^SKIP:' "$1".log))"
              return 0
            fi
            echo "::error::$1 neither concluded nor declared the expected skip on ${{ matrix.host }}"
            echo "        expected skip to mention: $3"
            tail -6 "$1".log 2>/dev/null | sed 's/^/        /'
            return 1
          }
          fail=0
          check 295_naming_the_host_target_changes_nothing.sh \
            "OK: naming the host's own target changes nothing" || fail=1
          check 296_what_the_report_names_is_what_the_link_line_uses.sh \
            "OK: what the report names is what the link line uses" || fail=1
          if [ "${{ matrix.host }}" = linux-x86_64 ]; then
            # The denominator: gcc is always installed here, so this host must
            # actually run the test.
            check 297_a_capability_pin_is_not_a_preference.sh \
              "OK: a capability pin is not a preference" || fail=1
          else
            check_or_declared_skip 297_a_capability_pin_is_not_a_preference.sh \
              "OK: a capability pin is not a preference" \
              "gcc is not installed here" || fail=1
          fi
          if [[ "${{ matrix.host }}" = linux-* ]]; then
            check 298_overriding_a_convention_requires_replacing_it.sh \
              "OK: a convention may be overridden, but not merely removed" || fail=1
          else
            # Non-Linux rows may restore a cache with no declared LLVM, and a
            # macOS host serves every gcc-pinned row through openkal-platform,
            # whose compiler is llvm: no row there is overridden by llvm.
            # Both Linux hosts require the assertion after native provisioning.
            check_or_declared_skip 298_overriding_a_convention_requires_replacing_it.sh \
              "OK: a convention may be overridden, but not merely removed" \
              "llvm is not installed here|served by a non-llvm convention" || fail=1
          fi

          # ── 2026.8.26.2: an answer mcpp already had, now used ─────────────
          #
          # Vocabulary completion is host-independent. The C-library query
          # additionally checks graph layering on both GNU Linux hosts.
          check 299_a_request_that_named_no_c_library_resolves_to_a_row_that_exists.sh \
            "OK: a request that named no C library resolves to a row that exists" || fail=1
          check 300_a_registered_family_is_not_reported_unknown.sh \
            "OK: a registered family is not reported unknown" || fail=1
          # 303's third half stacks a musl c-abi over this host's own target,
          # and not every host stacks that — an MSVC-ABI host answers the
          # layering question first, correctly, and there is then no
          # two-answer document to check. Both GNU Linux hosts must run all
          # three halves; a skip there is a failed assertion.
          if [[ "${{ matrix.host }}" = linux-* ]]; then
            check 303_the_query_gives_one_answer_for_the_c_library.sh \
              "OK: the query gives one answer for the C library" || fail=1
          else
            check_or_declared_skip 303_the_query_gives_one_answer_for_the_c_library.sh \
              "OK: the query gives one answer for the C library" \
              "refuses a musl c-abi over its own target" || fail=1
          fi

          # 301/302 NEED TWO COMPILER FAMILIES, AND THAT IS A PROPERTY OF THE
          # MACHINE RATHER THAN OF THE CLAIM. "A requirement that DIFFERS from
          # mcpp's own answer is applied" cannot be stated where only one family
          # exists — macOS ordinarily installs LLVM only. Both Linux hosts
          # now have LLVM and GCC payloads.
          #
          # AND THE DENOMINATOR IS linux-x86_64, WHICH HAS BOTH. Without a
          # host required to actually run these, a reason accepted everywhere is
          # a test that runs nowhere.
          if [ "${{ matrix.host }}" = linux-x86_64 ]; then
            check 301_the_graphs_compiler_is_taken_and_nothing_is_written.sh \
              "OK: the graph's compiler is taken and nothing is written" || fail=1
            check 302_a_stated_compiler_outranks_the_graph_and_two_requirements_do_not_stack.sh \
              "OK: a stated compiler outranks the graph and two requirements do not stack" || fail=1
          else
            check_or_declared_skip 301_the_graphs_compiler_is_taken_and_nothing_is_written.sh \
              "OK: the graph's compiler is taken and nothing is written" \
              "no other family is" || fail=1
            # 302's half two needs no second family and always runs; only half
            # one is skipped, so the file still reaches its conclusion.
            check 302_a_stated_compiler_outranks_the_graph_and_two_requirements_do_not_stack.sh \
              "OK: a stated compiler outranks the graph and two requirements do not stack" || fail=1
          fi
          [ "$fail" = 0 ] || exit 1

  scan:
    # 第二层:全表扫描,与仓库里的期望表比对。
    name: scan (${{ matrix.host }})
    needs: invariants
    runs-on: ${{ matrix.runner }}
    timeout-minutes: 120
    strategy:
      fail-fast: false
      matrix:
        include:
          # THE BUILD-HOST AXIS IS THE SET mcpp SHIPS FOR, NOT THE SET THAT
          # WAS CONVENIENT. `release.yml` publishes four: linux-x86_64,
          # linux-aarch64, macosx-arm64, windows-x86_64. A host mcpp is
          # distributed for and never scanned is a host whose target table is
          # a claim nobody checked.
          #
          # `host` IS (os, arch) AND NOT os. Two Linux hosts differ in which
          # rows they serve — `x86_64-linux-gnu` needs the host-native glibc
          # payload, so it is reachable on one and not the other — and a single
          # `linux` key would have them overwrite each other in expected.tsv.
          - { host: linux-x86_64,   runner: ubuntu-24.04     }
          - { host: linux-aarch64,  runner: ubuntu-24.04-arm }
          - { host: macos-arm64,    runner: macos-15         }
          - { host: windows-x86_64, runner: windows-2022     }
    defaults:
      run:
        shell: bash
    steps:
      - uses: actions/checkout@v4
      - uses: ./.github/actions/bootstrap-mcpp

      # This commit's mcpp: the one build.yml produced (use-built-mcpp, rule R1
      # of the 2026-10-02 CI record). Every leg runs on the image its artifact
      # was built on; the macOS leg moved to macos-15 when GitHub retired
      # macos-14 (2026-11-02), and with it the reason it built its own.
      - uses: ./.github/actions/use-built-mcpp
        with:
          host: ${{ matrix.host }}

      - name: Name this commit's mcpp MCPP_UNDER_TEST
        run: echo "MCPP_UNDER_TEST=$MCPP_FRESH" >> "$GITHUB_ENV"

      - name: Install the toolchains this matrix declares
        run: |
          set -uo pipefail
          export MCPP="$MCPP_UNDER_TEST"
          export MCPP_VENDORED_XLINGS="$XLINGS_BIN"
          want="$(awk -F'\t' -v h='${{ matrix.host }}' \
                    'NF>=11 && $2==h {print $4}' tests/matrix/expected.tsv \
                  | sort -u)"
          if [ -z "$want" ]; then
            echo "  ?   ${{ matrix.host }} 尚无期望行 —— 扫描它现有的工具链"
            exit 0
          fi
          fail=0
          for spec in $want; do
            fam="${spec%@*}"; ver="${spec#*@}"
            # `msvc@system` 是在机器上被找到的,不是装出来的。
            [ "$ver" = system ] && { echo "  ok  $spec (system)"; continue; }
            if "$MCPP" toolchain install "$fam" "$ver" >/dev/null 2>&1; then
              echo "  ok  $spec"
            else
              echo "::error::$spec 装不上,而期望表声明了它"
              fail=1
            fi
          done
          [ "$fail" = 0 ] || exit 1

      - name: Scan both systems
        run: |
          set -euo pipefail
          export MCPP="$MCPP_UNDER_TEST"
          export MCPP_VENDORED_XLINGS="$XLINGS_BIN"
          "$MCPP" self config --mirror GLOBAL 2>/dev/null || true
          # 编译器轴跟着**声明**走,不跟着「这台机器上装了什么」走。
          #
          # 实测 2026-08-26,同一个提交:PR 上这个 job 绿,合入 main 后红 —— 那
          # 次 windows-2022 恢复出来的缓存里多了一个 `gcc@16.1.0`,扫描产出 24
          # 格而期望表声明 16 格,八格全部报成「表里没有这一格」。缓存里有什么
          # 不是这个仓库声明了什么,而判据必须是后者。
          #
          # 与上一步取自同一列,所以「装它」和「扫它」不可能各说各话。
          MATRIX_COMPILERS="$(awk -F'\t' -v h='${{ matrix.host }}' \
                                'NF>=11 && $2==h {print $4}' tests/matrix/expected.tsv \
                              | sort -u | tr '\n' ' ')"
          export MATRIX_COMPILERS
          echo "declared compiler axis: ${MATRIX_COMPILERS:-<none — scanning what is installed>}"
          # 两种体系各自成表。scan 把 mode 写进第一列,而比对必须按 mode 分开
          # 做 —— 拿一种体系的测量去比整张表,另一种的每一行都会被报成「没跑到」。
          bash tests/matrix/scan.sh payload > measured-payload.tsv
          bash tests/matrix/scan.sh graph   > measured-graph.tsv
          cat measured-payload.tsv measured-graph.tsv > measured.tsv
          echo "--- measured ---"; cat measured.tsv

      # 上传排在比对之前,而这是刻意的次序。宿主的第一次运行本就没有期望行,
      # 比对会红 —— 而回填要用的正是这份产物。`if: always()` 也保留:一步失败不
      # 该把证据一起带走。
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: matrix-${{ matrix.host }}
          path: measured.tsv

      - name: Compare with the expected table
        run: |
          set -euo pipefail
          fail=0
          bash tests/matrix/compare.sh measured-payload.tsv \
               tests/matrix/expected.tsv ${{ matrix.host }} payload || fail=1
          bash tests/matrix/compare.sh measured-graph.tsv \
               tests/matrix/expected.tsv ${{ matrix.host }} graph || fail=1
          [ "$fail" = 0 ] || exit 1

      # A WEB ARTEFACT RUNS THROUGH THE INTERPRETER ITS PAYLOAD NAMES, NOT
      # THROUGH PATH. That is what `wasm32-emscripten`'s `verified` tier
      # claims, and no step measured it until a sandbox with no `node` on PATH
      # showed that the run depended on the host:
      #
      #   /usr/bin/env: 'node': No such file or directory
      #
      # A FRESH MCPP_HOME, BECAUSE THE CACHE IS NOT THE PUBLISHED FORM.
      # `~/.mcpp` is restored by key prefix, so the emsdk payload in it may
      # predate the recipe that writes `.mcpp-toolchain.json`, and that older
      # payload would be the object measured. A fresh home installs what the
      # index publishes today.
      #
      # AND A DECOY `node` FIRST ON PATH, rather than `node` removed from PATH.
      # Removing it would also remove whatever else those directories hold,
      # and an image that ships a real `node` would pass for the wrong reason.
      # A decoy that exits 97 with a marker separates the two outcomes on any
      # image: the payload's runner never reaches it.
      - name: "wasm32-emscripten runs through its payload's runner, not PATH"
        if: ${{ !cancelled() && matrix.host == 'linux-x86_64' }}
        run: |
          set -uo pipefail
          home=$(mktemp -d); work=$(mktemp -d); decoy=$(mktemp -d)
          printf '#!/bin/sh\necho "DECOY-NODE-WAS-RUN" >&2\nexit 97\n' > "$decoy/node"
          chmod +x "$decoy/node"
          export MCPP_HOME="$home" MCPP_VENDORED_XLINGS="$XLINGS_BIN"
          "$MCPP_UNDER_TEST" self config --mirror GLOBAL >/dev/null 2>&1 || true
          mkdir -p "$work/src"
          printf '[package]\nname = "w"\nversion = "0.1.0"\n' > "$work/mcpp.toml"
          cat > "$work/src/main.cpp" <<'CPP'
          import std;
          int main() {
            std::vector<int> v{3, 1, 2};
            std::ranges::sort(v);
            std::print("{}-{}-{}\n", v[0], v[1], v[2]);
          }
          CPP
          out=$(cd "$work" && PATH="$decoy:$PATH" "$MCPP_UNDER_TEST" run --target wasm32-emscripten 2>&1) && rc=0 || rc=$?
          printf '%s\n' "$out" | tail -12
          desc="$home/registry/data/xpkgs/xim-x-emsdk/6.0.9/.mcpp-toolchain.json"
          if [ ! -f "$desc" ]; then
            echo "::error::the freshly installed emsdk payload has no .mcpp-toolchain.json; the published recipe does not name its runner"
            exit 1
          fi
          if grep -q 'DECOY-NODE-WAS-RUN' <<<"$out"; then
            echo "::error::the artefact ran through the node on PATH, not through the payload's runner"
            exit 1
          fi
          if [ "$rc" -ne 0 ]; then
            echo "::error::mcpp run --target wasm32-emscripten exited $rc"
            exit 1
          fi
          if ! grep -qx '1-2-3' <<<"$out"; then
            echo "::error::the program's output line 1-2-3 is absent"
            exit 1
          fi
          echo "ok: wasm32-emscripten ran through the payload's runner; the decoy node was never run"
          # THE WEB-ROW SCRIPTS RUN HERE, OVER THE PAYLOAD THIS STEP HAS JUST
          # INSTALLED. The shards have no emsdk, and each of these leaves there
          # with 77 after its `SKIP:` line; until 2026-11-12 that exit was 0, the
          # shards reported them as passes, and 650, 653 and 657 ran on no
          # runner. A status other than 0 fails the step, 77 included.
          for t in 650_wasm_row_names_its_launcher.sh \
                   653_exceptions_is_the_second_abi_member.sh \
                   657_a_build_program_under_the_web_row_uses_the_host_compiler.sh \
                   981_a_web_link_has_the_profiles_level_and_the_wasm_exception_model.sh \
                   1079_an_emscripten_rows_longjmp_model_round_trips.sh; do
            echo "::group::e2e $t"
            MCPP="$MCPP_UNDER_TEST" bash "tests/e2e/$t" && rc=0 || rc=$?
            echo "::endgroup::"
            if [ "$rc" -ne 0 ]; then
              echo "::error::e2e $t ended with $rc over the installed emsdk (77: it skipped itself)"
              exit 1
            fi
          done

  coverage:
    # THE DENOMINATOR. Every check above is per host, and no per-host check
    # can notice a host that never ran.
    #
    # Each `scan` job compares the rows for ITS OWN host, so deleting a host
    # from the matrix above silently retires every expectation the table holds
    # for it: nothing measures those rows, nothing compares them, and the
    # workflow is green. This job is the one place that reads the expected table
    # as a whole and requires the run to have covered it.
    #
    # It runs even when a scan failed, because "which hosts were covered" is a
    # different question from "did they pass" — and a run where a host is
    # missing entirely should say so in those words rather than leaving a
    # reader to infer it from a job list. Not in a cancelled run: `always()`
    # queued it for a runner after the cancellation, and the concurrency group
    # was held until it ran (run 43599371222: 8.5 minutes, the next run's
    # start delayed by 9.1).
    name: coverage (every host the table names was scanned)
    needs: scan
    if: ${{ !cancelled() }}
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4
      - uses: actions/download-artifact@v4
        with:
          pattern: matrix-*
          path: measured
      - name: Every host in expected.tsv produced rows
        run: |
          set -euo pipefail
          want=$(awk -F'\t' 'NF>=11 {print $2}' tests/matrix/expected.tsv | sort -u)
          [ -n "$want" ] || { echo "::error::expected.tsv names no host at all"; exit 1; }
          got=$(cat measured/*/measured.tsv 2>/dev/null \
                | awk -F'\t' 'NF>=11 {print $2}' | sort -u)
          echo "expected hosts: $(echo $want)"
          echo "scanned hosts:  $(echo ${got:-<none>})"
          fail=0
          for h in $want; do
            printf '%s\n' "$got" | grep -qx "$h" || {
              echo "::error::expected.tsv holds rows for '$h', and no scan produced any"
              fail=1
            }
          done
          # AND THE OTHER DIRECTION. A host that scanned but has no rows in the
          # table is a new build host nobody declared expectations for — the
          # per-host compare already reds on it, but saying it here names the
          # cause rather than listing 40 unexplained cells.
          for h in $got; do
            printf '%s\n' "$want" | grep -qx "$h" || {
              echo "::error::'$h' was scanned and the expected table does not mention it"
              echo "        add its rows to tests/matrix/expected.tsv from this run's artifact"
              fail=1
            }
          done
          [ "$fail" = 0 ] || exit 1
          echo "OK: every build host the table names was scanned, and no other"

      - name: The build hosts mcpp ships for are the ones scanned
        run: |
          set -euo pipefail
          # THE TABLE AND THE RELEASE MUST NAME THE SAME SET. A host that
          # gets a published binary and no scan is a host whose target table is
          # a claim nobody checked; a host that is scanned and never shipped is
          # coverage spent on a machine no user has.
          #
          # Derived from release.yml's asset names rather than restated here, so
          # adding a fifth host to the release fails this step until the matrix
          # covers it.
          ship=$(grep -oE 'mcpp-\$\{?[A-Za-z_{}. ]*\}?-(linux|macosx|windows)-(x86_64|aarch64|arm64)' \
                   .github/workflows/release.yml \
                 | sed -E 's/.*-(linux|macosx|windows)-/\1-/' \
                 | sed 's/^macosx-/macos-/' | sort -u)
          scanned=$(awk -F'\t' 'NF>=11 {print $2}' tests/matrix/expected.tsv | sort -u)
          echo "release publishes: $(echo $ship)"
          echo "matrix declares:   $(echo $scanned)"
          if [ "$ship" != "$scanned" ]; then
            echo "::error::the set of build hosts mcpp publishes and the set the target matrix declares differ"
            diff <(printf '%s\n' "$ship") <(printf '%s\n' "$scanned") | sed 's/^/        /' || true
            exit 1
          fi
          echo "OK: $(printf '%s\n' "$ship" | wc -l) build hosts, published and scanned"