pr.yml

name: PR

# The only CI a pull request runs. Pushes to main and develop, and tags, are covered
# by the CircleCI config; this workflow mirrors its build-test workflow, not release.
on:
  pull_request:

concurrency:
  group: pr-${{ github.event.pull_request.number }}
  cancel-in-progress: true

env:
  # The OMG training corpus is not vendored. Requiring it here turns "corpus
  # absent" into a test failure instead of a skip, so the gate cannot pass green
  # without actually running (see tests/corpus/training_examples_test.go).
  OPENSYSML_REQUIRE_TRAINING_CORPUS: "1"
  # Same for the three pinned OMG pilot corpora, which are downloaded below and
  # gated by tests/corpus/pilot_corpora_test.go.
  OPENSYSML_REQUIRE_PILOT_CORPORA: "1"
  # Same for the pinned OMG PSSM test suite, gated by tools/referee/pssm and tools/cmd/pssm-referee.
  OPENSYSML_REQUIRE_PSSM_SUITE: "1"
  # Same for the pinned OMG SysML v1 to v2 transformation model, gated by tools/census/transformation.
  OPENSYSML_REQUIRE_SYSML_V1TOV2: "1"
  # Same for the pinned fUML reference-implementation suite, gated by tools/referee/fuml.
  OPENSYSML_REQUIRE_FUML_SUITE: "1"
  # Same for the pilot's XMI of the standard library, downloaded below and
  # compared against by tests/identity (TestPilotLibraryXMI).
  OPENSYSML_REQUIRE_PILOT_LIBRARY_XMI: "1"
  # z3 is installed below, so "no solver, therefore skip" would exercise nothing:
  # this turns an absent solver into a failure (see internal/exec/solve).
  OPENSYSML_REQUIRE_SMT: "1"
  # The WebAssembly gate runs the wasm binaries under Node 24, set up by its jobs;
  # without a runtime it would skip instead of proving they run (see tests/wasm).
  OPENSYSML_REQUIRE_WASM: "1"
  # Same for the Modelica Reference-FMUs, downloaded below and gated by
  # tests/fmi and the Python runner's real test: absent means failure, not skip.
  OPENSYSML_REQUIRE_REFERENCE_FMUS: "1"

jobs:
  # Which areas the pull request touches. A path no area claims turns every area
  # on, so a new directory is over-tested rather than untested.
  changes:
    name: Changed areas
    runs-on: ubuntu-latest
    permissions:
      contents: read
    timeout-minutes: 5
    outputs:
      go: ${{ steps.areas.outputs.go }}
      docs: ${{ steps.areas.outputs.docs }}
      node: ${{ steps.areas.outputs.node }}
      python: ${{ steps.areas.outputs.python }}
      java: ${{ steps.areas.outputs.java }}
      rust: ${{ steps.areas.outputs.rust }}
      julia: ${{ steps.areas.outputs.julia }}
      matlab: ${{ steps.areas.outputs.matlab }}
      vscode: ${{ steps.areas.outputs.vscode }}
      mdk: ${{ steps.areas.outputs.mdk }}
      syson: ${{ steps.areas.outputs.syson }}
    steps:
      - name: Check out repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Test the area filter
        run: scripts/ci-changed-areas-test.sh

      - name: Decide which areas to run
        id: areas
        env:
          BASE_REF: ${{ github.base_ref }}
        run: scripts/ci-changed-areas.sh "origin/$BASE_REF" HEAD | tee -a "$GITHUB_OUTPUT"

  race-tests:
    name: Go race tests (${{ matrix.shard }})
    needs: changes
    if: needs.changes.outputs.go == 'true'
    # The shards split the suite's slowest packages across runners so each gets its own job cap (see scripts/race-shard.sh).
    strategy:
      fail-fast: false
      matrix:
        shard: [runtime, model, export, rest]
    runs-on: ubuntu-latest
    permissions:
      contents: read
    timeout-minutes: 60
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Set up Go
        uses: actions/setup-go@v5
        with:
          go-version-file: go.mod
          cache: true

      # Node 24, as the WebAssembly gate pins: Node 22's WASI host crashes on the wasm binaries.
      - name: Set up Node
        uses: actions/setup-node@v4
        with:
          node-version: '24'

      - name: Download Go modules
        run: go mod download

      # Pinned by digest, so a substituted asset is not run. The release binary rather
      # than `go run` keeps buf's own module tree out of the checksum-database path.
      - name: Install buf
        if: matrix.shard == 'rest'
        run: |
          curl -fsSL --proto '=https' --proto-redir '=https' -o /tmp/buf \
            https://github.com/bufbuild/buf/releases/download/v1.57.2/buf-Linux-x86_64
          echo "644e6fa4a62afc2b0d425d3ac9538d2f512947c0f2e82fc95c41a5eab6729414  /tmp/buf" | sha256sum --check --strict
          sudo install -m 0755 /tmp/buf /usr/local/bin/buf
          buf --version

      # One buf template generates both the Go stubs and the Java client's message
      # classes, so without this check the committed stubs can drift from the schema.
      # `git add -N` puts a regenerated file the commit had deleted into the diff.
      - name: Verify the committed Go and Java stubs are current
        if: matrix.shard == 'rest'
        run: |
          make proto-buf BUF=buf
          git add -N api/proto \
            client/java/opensysml-client/src/main/java/org/openmbee/opensysml/proto
          git diff --exit-code api/proto \
            client/java/opensysml-client/src/main/java/org/openmbee/opensysml/proto

      # The solver is an external process, never linked in: the solver-dependent
      # tests need one on PATH to run rather than skip.
      - name: Install Z3
        run: |
          sudo apt-get update
          sudo apt-get install -y z3
          z3 --version

      # The second verified backend, for the portability gate below: cvc5 has no
      # apt package, so the official static release is what CI runs, pinned by
      # digest so a substituted asset is not run.
      - name: Install cvc5
        run: |
          curl -fsSL --proto '=https' --proto-redir '=https' -o /tmp/cvc5.zip \
            https://github.com/cvc5/cvc5/releases/download/cvc5-1.3.4/cvc5-Linux-x86_64-static.zip
          echo "dcdbfada0ce493ee98259c0816e0daafc561c223aadb3af298c2968e73ea39c6  /tmp/cvc5.zip" | sha256sum --check --strict
          unzip -p /tmp/cvc5.zip '*/bin/cvc5' > /tmp/cvc5-bin
          sudo install -m 0755 /tmp/cvc5-bin /usr/local/bin/cvc5
          cvc5 --version | head -1

      # Keyed on the download script and the shared pilot pin, so a change to the
      # pinned tag or the layout invalidates the cache. A restored cache is still
      # verified below.
      - name: Cache the OMG training corpus
        uses: actions/cache@v4
        with:
          path: examples/sysml-v2-training
          key: training-corpus-${{ hashFiles('scripts/download-training-examples.sh', 'scripts/pilot-pin.sh') }}

      - name: Download the OMG training corpus
        run: ./scripts/download-training-examples.sh

      - name: Verify the OMG training corpus
        run: |
          count=$(find examples/sysml-v2-training -name '*.sysml' | wc -l)
          echo "training corpus: $count .sysml files"
          if [ "$count" -eq 0 ]; then
            echo "error: the training corpus is empty; the corpus gate would not run" >&2
            exit 1
          fi

      # Same keying as the training corpus: the download script plus the shared
      # pilot pin. A restored cache is verified below rather than trusted.
      - name: Cache the OMG pilot corpora
        uses: actions/cache@v4
        with:
          path: examples/pilot-corpora
          key: pilot-corpora-${{ hashFiles('scripts/download-pilot-corpora.sh', 'scripts/pilot-pin.sh') }}

      - name: Download the OMG pilot corpora
        run: ./scripts/download-pilot-corpora.sh

      - name: Verify the OMG pilot corpora
        run: |
          for root in sysml-examples sysml-validation kerml-examples; do
            count=$(find "examples/pilot-corpora/$root" -type f \( -name '*.sysml' -o -name '*.kerml' \) | wc -l)
            echo "pilot corpus $root: $count model files"
            if [ "$count" -eq 0 ]; then
              echo "error: pilot corpus $root is empty; the corpora gate would not run" >&2
              exit 1
            fi
          done

      # The PSSM suite is one pinned file; keyed on its download script and pin.
      - name: Cache the OMG PSSM test suite
        uses: actions/cache@v4
        with:
          path: build/pssm
          key: pssm-suite-${{ hashFiles('scripts/download-pssm-suite.sh', 'scripts/pssm-pin.sh') }}

      - name: Download the OMG PSSM test suite
        run: ./scripts/download-pssm-suite.sh

      # The SysML v1 to v2 transformation model is one pinned file; keyed on its
      # download script and pin.
      - name: Cache the SysML v1 to v2 transformation model
        uses: actions/cache@v4
        with:
          path: build/sysml-v1tov2
          key: sysml-v1tov2-${{ hashFiles('scripts/download-sysml-v1tov2.sh', 'scripts/sysml-v1tov2-pin.sh') }}

      - name: Download the SysML v1 to v2 transformation model
        run: ./scripts/download-sysml-v1tov2.sh

      # The fUML reference implementation's models and jar, checksummed; keyed
      # on its download script and pin. Never run in CI: the Go tests read the
      # committed expected-record (docs/project/fuml-referee.md).
      - name: Cache the fUML reference-implementation suite
        uses: actions/cache@v4
        with:
          path: build/fuml
          key: fuml-suite-${{ hashFiles('scripts/download-fuml-suite.sh', 'scripts/fuml-pin.sh') }}

      - name: Download the fUML reference-implementation suite
        run: ./scripts/download-fuml-suite.sh

      # The pilot's XMI of the standard library, one subtree of the release
      # repository; keyed on its download script and the shared pilot pin.
      - name: Cache the pilot library XMI
        uses: actions/cache@v4
        with:
          path: build/pilot-library-xmi
          key: pilot-library-xmi-${{ hashFiles('scripts/download-pilot-library-xmi.sh', 'scripts/pilot-pin.sh') }}

      - name: Download the pilot library XMI
        run: ./scripts/download-pilot-library-xmi.sh

      # The FMI gate's simulator: the reference runner (client/python) is a
      # Python subprocess, so the library it drives is installed here, pinned
      # and wheel-only like every pip install of this workflow.
      - name: Install fmpy
        run: pip install --only-binary ":all:" fmpy==0.3.32

      # The Modelica Reference-FMUs, checksummed; keyed on the download script
      # and its pin. A restored cache is verified by the script's own check.
      - name: Cache the Reference-FMUs
        uses: actions/cache@v4
        with:
          path: examples/reference-fmus
          key: reference-fmus-${{ hashFiles('scripts/download-reference-fmus.sh', 'scripts/reference-fmus-pin.sh') }}

      - name: Download the Reference-FMUs
        run: ./scripts/download-reference-fmus.sh

      # Per-package timeout: under -race the runtime package runs 22-29 minutes on
      # these runners. Matches `make test-shard`.
      - name: Run Go race tests
        env:
          SHARD: ${{ matrix.shard }}
        run: make test-shard SHARD="$SHARD"

      - name: Upload coverage artifact
        uses: actions/upload-artifact@v4
        with:
          name: coverage-${{ matrix.shard }}
          path: coverage.txt
          if-no-files-found: error

  race-coverage:
    name: Go race coverage
    needs: race-tests
    runs-on: ubuntu-latest
    permissions:
      contents: read
    timeout-minutes: 5
    # The shard package sets are disjoint, so their blocks concatenate under one mode line.
    steps:
      - name: Download shard profiles
        uses: actions/download-artifact@v4
        with:
          pattern: coverage-*
          path: shards

      - name: Merge the shard profiles
        run: |
          set -euo pipefail
          profiles=(shards/coverage-*/coverage.txt)
          # One per race-tests shard.
          if [ "${#profiles[@]}" -ne 4 ]; then echo "error: expected 4 shard profiles, found ${#profiles[@]}" >&2; exit 1; fi
          for f in "${profiles[@]}"; do
            [ "$(head -n 1 "$f")" = "mode: atomic" ] || { echo "error: $f is not an atomic-mode profile" >&2; exit 1; }
          done
          { echo "mode: atomic"; for f in "${profiles[@]}"; do tail -n +2 "$f"; done; } > coverage.txt
          wc -l coverage.txt

      - name: Upload coverage artifact
        uses: actions/upload-artifact@v4
        with:
          name: coverage
          path: coverage.txt
          if-no-files-found: error

  static-and-integrity:
    name: Go static and integrity checks
    needs: changes
    if: needs.changes.outputs.go == 'true'
    runs-on: ubuntu-latest
    permissions:
      contents: read
    timeout-minutes: 30
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Set up Go
        uses: actions/setup-go@v5
        with:
          go-version-file: go.mod
          cache: true

      - name: Download Go modules
        run: go mod download

      - name: Install Z3
        run: |
          sudo apt-get update
          sudo apt-get install -y z3
          z3 --version

      - name: Install cvc5
        run: |
          curl -fsSL --proto '=https' --proto-redir '=https' -o /tmp/cvc5.zip \
            https://github.com/cvc5/cvc5/releases/download/cvc5-1.3.4/cvc5-Linux-x86_64-static.zip
          echo "dcdbfada0ce493ee98259c0816e0daafc561c223aadb3af298c2968e73ea39c6  /tmp/cvc5.zip" | sha256sum --check --strict
          unzip -p /tmp/cvc5.zip '*/bin/cvc5' > /tmp/cvc5-bin
          sudo install -m 0755 /tmp/cvc5-bin /usr/local/bin/cvc5
          cvc5 --version | head -1

      # Every corpus below comes through this downloader, so it is checked first.
      - name: Test the pilot downloader
        run: scripts/pilot-pin-test.sh

      # install.sh and install.ps1 against a release served from localhost.
      - name: Test the install scripts
        run: scripts/install-test.sh

      - name: Cache the OMG training corpus
        uses: actions/cache@v4
        with:
          path: examples/sysml-v2-training
          key: training-corpus-${{ hashFiles('scripts/download-training-examples.sh', 'scripts/pilot-pin.sh') }}

      - name: Download the OMG training corpus
        run: ./scripts/download-training-examples.sh

      - name: Verify the OMG training corpus
        run: |
          count=$(find examples/sysml-v2-training -name '*.sysml' | wc -l)
          echo "training corpus: $count .sysml files"
          if [ "$count" -eq 0 ]; then
            echo "error: the training corpus is empty; the corpus gate would not run" >&2
            exit 1
          fi

      - name: Cache the OMG pilot corpora
        uses: actions/cache@v4
        with:
          path: examples/pilot-corpora
          key: pilot-corpora-${{ hashFiles('scripts/download-pilot-corpora.sh', 'scripts/pilot-pin.sh') }}

      - name: Download the OMG pilot corpora
        run: ./scripts/download-pilot-corpora.sh

      - name: Verify the OMG pilot corpora
        run: |
          for root in sysml-examples sysml-validation kerml-examples; do
            count=$(find "examples/pilot-corpora/$root" -type f \( -name '*.sysml' -o -name '*.kerml' \) | wc -l)
            echo "pilot corpus $root: $count model files"
            if [ "$count" -eq 0 ]; then
              echo "error: pilot corpus $root is empty; the corpora gate would not run" >&2
              exit 1
            fi
          done

      - name: Cache the OMG PSSM test suite
        uses: actions/cache@v4
        with:
          path: build/pssm
          key: pssm-suite-${{ hashFiles('scripts/download-pssm-suite.sh', 'scripts/pssm-pin.sh') }}

      - name: Download the OMG PSSM test suite
        run: ./scripts/download-pssm-suite.sh

      - name: Cache the SysML v1 to v2 transformation model
        uses: actions/cache@v4
        with:
          path: build/sysml-v1tov2
          key: sysml-v1tov2-${{ hashFiles('scripts/download-sysml-v1tov2.sh', 'scripts/sysml-v1tov2-pin.sh') }}

      - name: Download the SysML v1 to v2 transformation model
        run: ./scripts/download-sysml-v1tov2.sh

      - name: Cache the fUML reference-implementation suite
        uses: actions/cache@v4
        with:
          path: build/fuml
          key: fuml-suite-${{ hashFiles('scripts/download-fuml-suite.sh', 'scripts/fuml-pin.sh') }}

      - name: Download the fUML reference-implementation suite
        run: ./scripts/download-fuml-suite.sh

      # The pilot's XMI of the standard library, one subtree of the release
      # repository; keyed on its download script and the shared pilot pin.
      - name: Cache the pilot library XMI
        uses: actions/cache@v4
        with:
          path: build/pilot-library-xmi
          key: pilot-library-xmi-${{ hashFiles('scripts/download-pilot-library-xmi.sh', 'scripts/pilot-pin.sh') }}

      - name: Download the pilot library XMI
        run: ./scripts/download-pilot-library-xmi.sh

      - name: Check Go formatting
        run: |
          unformatted=$(gofmt -l .)
          if [ -n "$unformatted" ]; then
            echo "The following files are not gofmt'd:"
            echo "$unformatted"
            exit 1
          fi

      - name: Run Go vet
        run: |
          go vet ./...
          go vet -C tools ./...

      - name: Vet and test the production sysml build (-tags sysml_prod)
        run: |
          go vet -tags sysml_prod ./cmd/sysml/... ./internal/frontend/repl/...
          go test -count=1 -tags sysml_prod ./cmd/sysml -run TestProdBuild

      - name: Run static analysis (staticcheck + gosec)
        run: make lint

      # The embedded library snapshot is generated from the bundled OMG files;
      # a change to either without regenerating it must not land.
      - name: Check the library snapshot is current
        run: make stdlib-snapshot-check

      - name: Check grpc-go stays out of production code
        run: ./scripts/check-grpc-imports.sh

      - name: Lint the protobuf schema
        run: make proto-lint

      # Wire compatibility against the branch this pull request merges into;
      # the baseline is a git archive, so a shallow fetch of it is enough.
      - name: Check the protobuf schema for breaking changes
        env:
          BASE_REF: ${{ github.base_ref }}
        run: |
          git fetch --no-tags --depth=1 origin "$BASE_REF"
          make proto-breaking BUF_BREAKING_REF="origin/$BASE_REF"

      # Race shards skip tests gated here; keep Makefile RACE_SHARD_SKIP and RACE_SHARD_TOOLS_SKIP in sync.
      # Re-run the corpus gate on its own so its verdict is legible in the log
      # and a skip is impossible to miss. TestCorpusGates is the shared
      # cache-independence case over all four OMG roots, which skips with them.
      - name: Run training corpus gate
        run: |
          set -o pipefail
          go test -count=1 -v ./tests/corpus -run 'TestTrainingExamples|TestCorpusGates' | tee corpus-gate.log
          grep -E 'training files clean' corpus-gate.log
          if grep -qE '^\s*--- SKIP' corpus-gate.log; then
            echo "error: the corpus gate skipped" >&2
            exit 1
          fi

      # The pilot corpora gate on its own, for the same reason: its per-root
      # verdict lines are the reviewable output, and a skip must not pass.
      # It gates our own diagnostics only; the comparison against the reference
      # implementation (tools/referee/diff) needs Java validators and is not run here.
      - name: Run pilot corpora gate
        run: |
          set -o pipefail
          go test -count=1 -v ./tests/corpus -run 'TestPilotCorpora' | tee pilot-corpora-gate.log
          grep -E 'pilot corpus files clean' pilot-corpora-gate.log
          if grep -qE '^\s*--- SKIP' pilot-corpora-gate.log; then
            echo "error: the pilot corpora gate skipped" >&2
            exit 1
          fi

      # The normative-identity gate alone, for the same reason: its one verdict
      # line names the counts, and a skip cannot hide behind a green suite.
      - name: Run pilot library identity gate
        run: |
          set -o pipefail
          go test -count=1 -v ./tests/identity -run 'TestPilotLibraryXMI' | tee pilot-library-xmi-gate.log
          grep -E 'pilot library XMI: [0-9]+ derived' pilot-library-xmi-gate.log
          if grep -qE '^\s*--- SKIP' pilot-library-xmi-gate.log; then
            echo "error: the pilot library identity gate skipped" >&2
            exit 1
          fi

      # The PSSM suite gates on their own, so a skip cannot hide behind a green suite.
      - name: Run PSSM suite gates
        run: |
          set -o pipefail
          go test -C tools -count=1 -v ./referee/pssm -run 'TestSuiteRead|TestSuiteClassification|TestEmitSuite' | tee pssm-gate.log
          if grep -qE '^\s*--- SKIP' pssm-gate.log; then
            echo "error: the PSSM suite gate skipped" >&2
            exit 1
          fi

      # Bucket counts only, never pass/fail; see docs/project/pssm-referee.md.
      - name: PSSM referee reproduces its baseline counts
        run: go run -C tools ./cmd/pssm-referee -check

      # The transformation census's baseline lists the mapping classes the
      # pinned model declares; here the model is provisioned, so the baseline
      # is compared against a fresh extraction.
      - name: Transformation census lists what the pinned model contains
        run: go run -C tools ./cmd/transformation-census -check -require-xmi

      # The migration of the PSSM suite to v2 notation on its own, so its report
      # totals are legible in the log and a skip must not pass; see
      # docs/project/pssm-migration.md.
      - name: Run PSSM migration gate
        run: |
          set -o pipefail
          go test -count=1 -v ./tests/corpus -run 'TestPSSMSuiteMigration' | tee pssm-migration-gate.log
          grep -E 'PSSM_TestSuite.xmi: migrated [0-9]+ element' pssm-migration-gate.log
          if grep -qE '^\s*--- SKIP' pssm-migration-gate.log; then
            echo "error: the PSSM migration gate skipped" >&2
            exit 1
          fi

      # The fUML reader and classifier over the pinned models on their own, likewise.
      - name: Run fUML suite gates
        run: |
          set -o pipefail
          go test -C tools -count=1 -v ./referee/fuml -run 'TestSuite' | tee fuml-gate.log
          if grep -qE '^\s*--- SKIP' fuml-gate.log; then
            echo "error: the fUML suite gate skipped" >&2
            exit 1
          fi

      # Bucket counts only, never pass/fail; see docs/project/fuml-referee.md.
      - name: fUML referee reproduces its baseline counts
        run: go run -C tools ./cmd/fuml-referee -check

      # The RDF round-trip ratchet over every example on its own, so its
      # per-verdict counts are legible in the log and a skip must not pass.
      # The round-trip gates stay in the race shards too: their worker pool converts files concurrently.
      - name: Run RDF corpus round-trip gate
        run: |
          set -o pipefail
          go test -count=1 -v ./tests/corpus -run 'TestCorpusRoundTrip' | tee corpus-roundtrip-gate.log
          grep -E 'corpus round trip: [0-9]+ files:' corpus-roundtrip-gate.log
          if grep -qE '^\s*--- SKIP' corpus-roundtrip-gate.log; then
            echo "error: the RDF corpus round-trip gate skipped" >&2
            exit 1
          fi

      - name: Run api-json corpus round-trip gate
        run: |
          set -o pipefail
          go test -count=1 -v ./tests/corpus -run 'TestCorpusAPIJSONRoundTrip' | tee api-json-roundtrip-gate.log
          grep -E 'api-json corpus round trip: [0-9]+ files:' api-json-roundtrip-gate.log
          if grep -qE '^\s*--- SKIP' api-json-roundtrip-gate.log; then
            echo "error: the api-json corpus round-trip gate skipped" >&2
            exit 1
          fi

      # Re-run the solver gate on its own, as the corpus gate is, so a skip
      # cannot hide behind a green suite.
      - name: Run solver gate (Z3)
        run: |
          set -o pipefail
          go test -count=1 -v ./internal/exec/solve ./internal/frontend/repl -run 'TestSolver|TestDiscovery|TestSolved|TestDivisor|TestCheck|TestSolve|TestConfigure|TestSynthesis|TestPinned|TestFixed|TestOptimize|TestOptimum' | tee solver-gate.log
          if grep -qE '^\s*--- SKIP' solver-gate.log; then
            echo "error: a solver-dependent test skipped" >&2
            exit 1
          fi

      # The differential gate compares the solver against the normative
      # evaluator; its summary counts make coverage drift reviewable in the log.
      - name: Run solver differential gate
        run: |
          set -o pipefail
          go test -count=1 -v ./internal/exec/solve -run TestDifferential | tee differential-gate.log
          grep -E 'differential gate .*: .* elements:' differential-gate.log
          if grep -qE '^\s*--- SKIP' differential-gate.log; then
            echo "error: a differential gate skipped" >&2
            exit 1
          fi

      # Portability: the same subset run against both verified backends, so a
      # feature one of them refuses is reported rather than discovered by a user.
      # OPENSYSML_REQUIRE_SMT makes an absent solver a failure, not a skip.
      - name: Run solver portability gate
        run: |
          set -o pipefail
          for solver in z3 cvc5; do
            OPENSYSML_SMT="$solver" go test -count=1 -v ./internal/exec/solve \
              -run 'TestPortability' | tee "portability-$solver.log"
            grep -E "portability of $solver" "portability-$solver.log"
            if grep -qE '^\s*--- SKIP' "portability-$solver.log"; then
              echo "error: the portability gate skipped for $solver" >&2
              exit 1
            fi
          done

      # The solver gate again against the second backend, not only the
      # portability subset: what z3 answers, cvc5 must answer too.
      - name: Run solver gate (cvc5)
        run: |
          set -o pipefail
          OPENSYSML_SMT=cvc5 go test -count=1 -v ./internal/exec/solve ./internal/frontend/repl \
            -run 'TestSolver|TestDiscovery|TestSolved|TestDivisor|TestCheck|TestSolve|TestConfigure|TestSynthesis|TestPinned|TestFixed|TestExplain|TestCore' \
            | tee cvc5-gate.log
          if grep -qE '^\s*--- SKIP' cvc5-gate.log; then
            echo "error: a solver-dependent test skipped under cvc5" >&2
            exit 1
          fi

      # The other half of the contract: with no solver to be found, every
      # solver-dependent test must skip with a reason and the absent-solver paths
      # must still report one. OPENSYSML_SMT names an executable that does not
      # exist, which is discovery's absent case, and the requirement flag is
      # dropped so a skip is the expected outcome here.
      - name: Run solver-absent gate
        run: |
          set -o pipefail
          env -u OPENSYSML_REQUIRE_SMT OPENSYSML_SMT=/nonexistent/no-such-solver \
            go test -count=1 -v ./internal/exec/solve ./internal/frontend/repl | tee no-solver-gate.log
          for name in TestCheckReportsAnAbsentSolver TestExplainReportsAnAbsentSolver \
            TestSolveReportsAnAbsentSolver TestConfigureReportsAnAbsentSolver \
            TestOptimizeReportsAnAbsentSolver; do
            grep -qE "^\s*--- PASS: $name" no-solver-gate.log || {
              echo "error: $name did not run without a solver" >&2
              exit 1
            }
          done

  wasm-gate:
    name: WebAssembly gate
    needs: changes
    if: needs.changes.outputs.go == 'true'
    runs-on: ubuntu-latest
    permissions:
      contents: read
    timeout-minutes: 20
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Set up Go
        uses: actions/setup-go@v5
        with:
          go-version-file: go.mod
          cache: true

      - name: Set up Node
        uses: actions/setup-node@v4
        with:
          node-version: '24'

      # It compiles and vets the whole tree for both wasm targets, links the commands
      # and runs them under Node, so a skip has to be visible and has to fail.
      - name: Run the WebAssembly gate
        run: |
          set -o pipefail
          node --version
          go test -count=1 -v ./tests/wasm | tee wasm-gate.log
          if grep -qE '^\s*--- SKIP' wasm-gate.log; then
            echo "error: the WebAssembly gate skipped" >&2
            exit 1
          fi

  # The Xpect oracle's committed baseline (docs/project/pilot-xpect-baseline.json)
  # used to be reproduced only by the nightly oracle-reproduction workflow, so a
  # checker change that moved a verdict surfaced a day after it merged. The check
  # needs no Java — only the pinned .xt suites — so it runs here on every change
  # that can move it: a rule under internal/ or a re-recorded baseline under docs/.
  xpect-oracle:
    name: Xpect oracle reproduces its baseline
    needs: changes
    if: needs.changes.outputs.go == 'true' || needs.changes.outputs.docs == 'true'
    runs-on: ubuntu-latest
    permissions:
      contents: read
    timeout-minutes: 10
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Set up Go
        uses: actions/setup-go@v5
        with:
          go-version-file: go.mod
          cache: true

      - name: Cache the pilot Xpect suites
        uses: actions/cache@v4
        with:
          path: build/pilot-xpect-corpus
          key: pilot-xpect-corpus-${{ hashFiles('scripts/download-pilot-xpect.sh', 'scripts/pilot-pin.sh') }}

      - name: Download the pilot Xpect suites
        run: ./scripts/download-pilot-xpect.sh

      - name: Xpect oracle reproduces its baseline
        run: go run -C tools ./cmd/pilot-xpect -check

  # The client jobs download this binary rather than building one, so it runs
  # whenever the service or any client does.
  build:
    name: Build binaries
    needs: changes
    if: |
      needs.changes.outputs.go == 'true' ||
      needs.changes.outputs.node == 'true' ||
      needs.changes.outputs.python == 'true' ||
      needs.changes.outputs.java == 'true' ||
      needs.changes.outputs.rust == 'true' ||
      needs.changes.outputs.julia == 'true' ||
      needs.changes.outputs.matlab == 'true' ||
      needs.changes.outputs.mdk == 'true' ||
      needs.changes.outputs.syson == 'true'
    runs-on: ubuntu-latest
    permissions:
      contents: read
    timeout-minutes: 15
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Set up Go
        uses: actions/setup-go@v5
        with:
          go-version-file: go.mod
          cache: true

      - name: Download Go modules
        run: go mod download

      - name: Build binaries
        run: |
          make build \
            VERSION="pr-${{ github.event.pull_request.number }}" \
            COMMIT="$(git rev-parse --short HEAD)" \
            BUILD_TIME="$(date -u '+%Y-%m-%d_%H:%M:%S')" \
            GO_VERSION="$(go version | awk '{print $3}')"

      - name: Build the combined WebAssembly module
        run: |
          mkdir -p bin/wasm
          GOOS=js GOARCH=wasm go build -trimpath -ldflags="-s -w" \
            -o bin/wasm/sysml-wasm.wasm ./cmd/sysml-wasm
          cp "$(go env GOROOT)/lib/wasm/wasm_exec.js" bin/wasm/

      - name: Verify binaries
        run: |
          ./bin/sysml --version
          ./bin/sysml-lsp --version
          ls -lh bin/
          make static-check

      - name: Upload binary artifacts
        uses: actions/upload-artifact@v4
        with:
          name: binaries
          path: bin/
          if-no-files-found: error

  # A gated job that did not run reports `skipped`, which this gate accepts; a job
  # skipped by a failed dependency is caught through that dependency's own result.
  build-and-test:
    name: Build and test
    if: always()
    needs:
      - changes
      - build
      - mdk-plugin
      - conformance-pkg
      - docs
      - java-test
      - julia-client
      - matlab-client
      - syson-plugin
      - node-test
      - pdf-toolchain
      - python-test
      - race-tests
      - race-coverage
      - rust-test
      - static-and-integrity
      - vscode-extension
      - wasm-gate
      - xpect-oracle
    runs-on: ubuntu-latest
    permissions:
      contents: read
    timeout-minutes: 5
    steps:
      - name: Verify required checks
        env:
          CHANGES_RESULT: ${{ needs.changes.result }}
          BUILD_RESULT: ${{ needs.build.result }}
          MDK_PLUGIN_RESULT: ${{ needs.mdk-plugin.result }}
          CONFORMANCE_PKG_RESULT: ${{ needs.conformance-pkg.result }}
          DOCS_RESULT: ${{ needs.docs.result }}
          JAVA_TEST_RESULT: ${{ needs.java-test.result }}
          JULIA_CLIENT_RESULT: ${{ needs.julia-client.result }}
          MATLAB_CLIENT_RESULT: ${{ needs.matlab-client.result }}
          SYSON_PLUGIN_RESULT: ${{ needs.syson-plugin.result }}
          NODE_TEST_RESULT: ${{ needs.node-test.result }}
          PDF_TOOLCHAIN_RESULT: ${{ needs.pdf-toolchain.result }}
          PYTHON_TEST_RESULT: ${{ needs.python-test.result }}
          RACE_TESTS_RESULT: ${{ needs.race-tests.result }}
          RACE_COVERAGE_RESULT: ${{ needs.race-coverage.result }}
          RUST_TEST_RESULT: ${{ needs.rust-test.result }}
          STATIC_AND_INTEGRITY_RESULT: ${{ needs.static-and-integrity.result }}
          VSCODE_EXTENSION_RESULT: ${{ needs.vscode-extension.result }}
          WASM_GATE_RESULT: ${{ needs.wasm-gate.result }}
          XPECT_ORACLE_RESULT: ${{ needs.xpect-oracle.result }}
        run: |
          ok() { [ "$1" = success ] || [ "$1" = skipped ]; }
          if [ "$CHANGES_RESULT" != success ] ||
             ! ok "$BUILD_RESULT" ||
             ! ok "$MDK_PLUGIN_RESULT" ||
             ! ok "$CONFORMANCE_PKG_RESULT" ||
             ! ok "$DOCS_RESULT" ||
             ! ok "$JAVA_TEST_RESULT" ||
             ! ok "$JULIA_CLIENT_RESULT" ||
             ! ok "$MATLAB_CLIENT_RESULT" ||
             ! ok "$SYSON_PLUGIN_RESULT" ||
             ! ok "$NODE_TEST_RESULT" ||
             ! ok "$PDF_TOOLCHAIN_RESULT" ||
             ! ok "$PYTHON_TEST_RESULT" ||
             ! ok "$RACE_TESTS_RESULT" ||
             ! ok "$RACE_COVERAGE_RESULT" ||
             ! ok "$RUST_TEST_RESULT" ||
             ! ok "$STATIC_AND_INTEGRITY_RESULT" ||
             ! ok "$VSCODE_EXTENSION_RESULT" ||
             ! ok "$WASM_GATE_RESULT" ||
             ! ok "$XPECT_ORACLE_RESULT"; then
            echo "changes=$CHANGES_RESULT"
            echo "build=$BUILD_RESULT"
            echo "mdk-plugin=$MDK_PLUGIN_RESULT"
            echo "conformance-pkg=$CONFORMANCE_PKG_RESULT"
            echo "docs=$DOCS_RESULT"
            echo "java-test=$JAVA_TEST_RESULT"
            echo "julia-client=$JULIA_CLIENT_RESULT"
            echo "matlab-client=$MATLAB_CLIENT_RESULT"
            echo "syson-plugin=$SYSON_PLUGIN_RESULT"
            echo "node-test=$NODE_TEST_RESULT"
            echo "pdf-toolchain=$PDF_TOOLCHAIN_RESULT"
            echo "python-test=$PYTHON_TEST_RESULT"
            echo "race-tests=$RACE_TESTS_RESULT"
            echo "race-coverage=$RACE_COVERAGE_RESULT"
            echo "rust-test=$RUST_TEST_RESULT"
            echo "static-and-integrity=$STATIC_AND_INTEGRITY_RESULT"
            echo "vscode-extension=$VSCODE_EXTENSION_RESULT"
            echo "wasm-gate=$WASM_GATE_RESULT"
            echo "xpect-oracle=$XPECT_ORACLE_RESULT"
            exit 1
          fi

  # The PDF backend drives external tools (WeasyPrint, pandoc, mermaid-cli,
  # KaTeX, Graphviz, the PlantUML jar) as subprocesses; the Go suite above
  # tests that contract with fakes. This job runs the integration tests
  # against the pinned toolchain, with an absent tool a failure, not a skip.
  pdf-toolchain:
    name: PDF toolchain tests
    needs: changes
    if: needs.changes.outputs.go == 'true'
    runs-on: ubuntu-latest
    permissions:
      contents: read
    timeout-minutes: 20
    env:
      OPENSYSML_REQUIRE_PDF_TOOLCHAIN: "1"
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Set up Go
        uses: actions/setup-go@v5
        with:
          go-version-file: go.mod
          cache: true

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '22'

      - name: Set up Python
        id: setup-python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Set up Java
        uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: '21'

      # Keyed on the provisioning script, whose pins and digests are the
      # toolchain's identity; the venv is not restored across Python builds.
      - name: Cache the PDF toolchain
        id: toolchain-cache
        uses: actions/cache@v4
        with:
          path: build/doc-pdf
          key: doc-pdf-toolchain-${{ runner.os }}-${{ hashFiles('scripts/download-doc-pdf-toolchain.sh') }}-py${{ steps.setup-python.outputs.python-version }}

      # WeasyPrint's venv links against the system's Pango, the browser
      # mermaid-cli launches needs its shared libraries, Graphviz's neato
      # layout plugin needs GTS; the tests read PDFs back with poppler-utils.
      - name: Install the toolchain's system libraries
        run: |
          sudo apt-get update
          sudo apt-get install -y --no-install-recommends libpango-1.0-0 libpangoft2-1.0-0 libharfbuzz-subset0 \
            libnss3 libatk-bridge2.0-0 libgbm1 libxkbcommon0 libasound2t64 fonts-dejavu-core libgts-0.7-5 \
            poppler-utils

      - name: Provision the PDF toolchain
        run: ./scripts/download-doc-pdf-toolchain.sh

      - name: Run the PDF integration tests
        env:
          OPENSYSML_PANDOC: ${{ github.workspace }}/build/doc-pdf/pandoc-3.10.2/bin/pandoc
          OPENSYSML_WEASYPRINT: ${{ github.workspace }}/build/doc-pdf/weasyprint/bin/weasyprint
          OPENSYSML_MMDC: ${{ github.workspace }}/build/doc-pdf/mermaid/node_modules/.bin/mmdc
          OPENSYSML_MMDC_PUPPETEER: ${{ github.workspace }}/build/doc-pdf/mermaid/puppeteer.json
          OPENSYSML_KATEX: ${{ github.workspace }}/build/doc-pdf/katex/node_modules/.bin/katex
          OPENSYSML_DOT: ${{ github.workspace }}/build/doc-pdf/graphviz/bin/dot
          OPENSYSML_PLANTUML_JAR: ${{ github.workspace }}/build/doc-pdf/plantuml/plantuml-1.2026.8.jar
          OPENSYSML_D2: ${{ github.workspace }}/build/doc-pdf/d2/d2-v0.9.0/bin/d2
        run: go test -count=1 -v -run Installed ./internal/ir/view ./internal/doc/docpdf ./tests/migrate

  vscode-extension:
    name: VS Code extension
    needs: changes
    if: needs.changes.outputs.vscode == 'true'
    runs-on: ubuntu-latest
    permissions:
      contents: read
    timeout-minutes: 10
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: npm
          cache-dependency-path: editors/vscode/package-lock.json

      # Type-check, bundle and package. The generated TextMate grammars are
      # gated by go test ./editors/... in the job above.
      - name: Package the VS Code extension
        run: make vscode-package

      - name: Build landing-page diagram bundle
        working-directory: editors/vscode
        run: npm run build:landing

      - name: Upload VS Code extension artifact
        uses: actions/upload-artifact@v4
        with:
          name: vscode-extension
          path: editors/vscode/opensysml-sysml.vsix
          if-no-files-found: error

  mdk-plugin:
    name: OpenSysML MDK plugin
    needs: [changes, build]
    if: needs.changes.outputs.mdk == 'true'
    runs-on: ubuntu-latest
    permissions:
      contents: read
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v4

      - uses: actions/download-artifact@v4
        with:
          name: binaries
          path: bin

      # 17 is the plugin's compile target (the oldest supported Cameo runs on it).
      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: '17'
          cache: maven

      - name: Make the service binary executable
        run: chmod +x bin/sysml-grpc

      - name: Install the Java client the plugin builds against
        run: mvn -B -q -f client/java/pom.xml -pl :opensysml -am install -DskipTests

      # Compiles against the compile-only OpenAPI stubs and runs the unit tests plus
      # the pipeline test against the freshly built service.
      - name: Build and test the plugin
        run: mvn -B -f editors/mdk/pom.xml verify -Dopensysml.requireService=true

  docs:
    name: Documentation site
    needs: changes
    if: needs.changes.outputs.docs == 'true'
    runs-on: ubuntu-latest
    permissions:
      contents: read
    timeout-minutes: 15
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'
          cache: pip
          cache-dependency-path: docs-requirements.txt

      - name: Set up Go
        uses: actions/setup-go@v5
        with:
          go-version-file: go.mod
          cache: true

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: npm
          cache-dependency-path: editors/vscode/package-lock.json

      - name: Install documentation toolchain
        run: make docs-install

      - name: Build the landing-page diagram
        run: make docs-landing-assets

      - name: Check documentation links
        run: python3 scripts/check-doc-links.py

      # The shipped pages are generated from each command's description, so a
      # flag added without regenerating them would ship a stale page.
      - name: Verify the committed manual pages are current
        run: |
          sudo apt-get update && sudo apt-get install -y --no-install-recommends mandoc
          make man-check

      # Internal work-item labels have no public referent, so they may not
      # appear in the pages a user reads.
      - name: Check for internal labels in reader-facing documentation
        run: python3 scripts/check-doc-ids.py

      # An oracle total quoted outside the generated block is a snapshot, and a
      # reader cannot tell that from a current figure unless the page says so.
      - name: Check quoted oracle figures name the round they measured
        run: python3 scripts/check-doc-figures.py

      # The census figures are derived from the committed baseline, and every
      # table row must be a constraint the baseline records (and vice versa).
      - name: Check the validation-constraint census matches its baseline
        run: go run -C tools ./cmd/validation-census -check

      # Same for the transformation census; this job provisions neither input,
      # so the model and measurement comparisons run in the gate job that does,
      # and the workflow-wide require variables are lifted here.
      - name: Check the transformation census matches its baseline
        env:
          OPENSYSML_REQUIRE_PSSM_SUITE: ""
          OPENSYSML_REQUIRE_SYSML_V1TOV2: ""
        run: go run -C tools ./cmd/transformation-census -check

      # Changelog entries live in changes/unreleased/ until a release folds them in.
      - name: Check changelog fragments
        run: python3 scripts/changelog-test.py && python3 scripts/changelog.py check

      - name: Check the release provenance writer
        run: python3 scripts/release-provenance-test.py

      # The compliance census is counted when the site is built, never committed.
      - name: Check the compliance census hook
        run: python3 scripts/mkdocs_census-test.py

      # The test-suite figures are counted when the site is built, never committed.
      - name: Check the test-suite figures hook
        run: python3 scripts/mkdocs_suite_figures-test.py

      # Sphinx roles in the Python docstrings are rewritten when the site is built.
      - name: Check the Sphinx-role rewriting hook
        run: python3 scripts/griffe_sphinx_roles-test.py

      # The install scripts are served from the site root, copied from the tree.
      - name: Check the install-script publishing hook
        run: python3 scripts/mkdocs_install_scripts-test.py

      # --strict: a link or anchor a moved page left behind fails here rather than
      # publishing a 404 from main.
      - name: Build documentation site
        run: make docs

  node-test:
    name: Node client tests
    needs: [changes, build]
    if: needs.changes.outputs.node == 'true'
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v4

      # The client verifies a download against the copy of the pinned digests it
      # ships, so a copy that drifts from the table pins something else.
      - name: Check the clients ship the pinned release digests
        run: python3 scripts/sync-release-digests.py --check

      - uses: actions/download-artifact@v4
        with:
          name: binaries
          path: bin

      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: npm
          cache-dependency-path: client/node/package-lock.json

      # The tests and the conformance runner start private children of this
      # binary; without it they would build one from the checkout, needing Go.
      - name: Install the sysml-grpc binary
        run: |
          chmod +x bin/sysml-grpc
          echo "OPENSYSML_BINARY=$(pwd)/bin/sysml-grpc" >> "$GITHUB_ENV"
          echo "OPENSYSML_WASM=$(pwd)/bin/wasm/sysml-wasm.wasm" >> "$GITHUB_ENV"
          echo "OPENSYSML_WASM_EXEC=$(pwd)/bin/wasm/wasm_exec.js" >> "$GITHUB_ENV"
          echo "OPENSYSML_REQUIRE_WASM=1" >> "$GITHUB_ENV"

      - name: Install the client's dependencies
        working-directory: client/node
        # --ignore-scripts: no dependency of this client needs an install hook,
        # and one added upstream would run here with the workflow's token.
        run: npm ci --ignore-scripts

      - name: Build, typecheck and lint
        working-directory: client/node
        run: |
          npm run build
          npm run typecheck
          npm run lint

      # The verification tests ask the service solver-backed questions; the
      # solver is an external process the service finds on PATH.
      - name: Install Z3
        run: |
          sudo apt-get update
          sudo apt-get install -y z3
          z3 --version

      - name: Run the tests
        working-directory: client/node
        run: npm test

      # --allow-skips because three scenarios ask for a request the client's
      # public API refuses before asking the service; the skipped count is
      # reported and the artifact records which scenarios they were.
      - name: Run the conformance suite through the client
        working-directory: client/node
        run: |
          npm run conformance -- --binary "$OPENSYSML_BINARY" --allow-skips \
            --report node-conformance.json

      # A runner that passes against a deliberately broken client tests nothing.
      - name: Check the conformance runner catches a broken client
        working-directory: client/node
        run: |
          for mutation in hide-capability drop-diagnostics blank-symbol-kind shift-integer drop-feature-values; do
            if npm run conformance -- --binary "$OPENSYSML_BINARY" --allow-skips \
                 --protocols connect --mutate "$mutation" > /dev/null 2>&1; then
              echo "error: the suite passed with the $mutation mutation applied" >&2
              exit 1
            fi
            echo "ok: $mutation is caught"
          done

      - uses: actions/upload-artifact@v4
        with:
          name: node-conformance
          path: client/node/node-conformance.json

      # Pinned by digest, as cvc5 is above, so a substituted asset is not run.
      - name: Install buf
        run: |
          curl -fsSL --proto '=https' --proto-redir '=https' -o /tmp/buf \
            https://github.com/bufbuild/buf/releases/download/v1.57.2/buf-Linux-x86_64
          echo "644e6fa4a62afc2b0d425d3ac9538d2f512947c0f2e82fc95c41a5eab6729414  /tmp/buf" | sha256sum --check --strict
          sudo install -m 0755 /tmp/buf /usr/local/bin/buf
          buf --version

      # Committed stubs must be what buf generates, or the checked-in client and
      # the schema can drift apart silently.
      - name: Verify the committed TypeScript stubs are current
        run: |
          make proto-ts BUF=buf
          git add -N client/node/src/generated
          git diff --exit-code client/node/src/generated

  python-test:
    name: Python client tests
    needs: [changes, build]
    if: needs.changes.outputs.python == 'true'
    runs-on: ubuntu-latest
    permissions:
      contents: read
    timeout-minutes: 10
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      # The client verifies a download against the copy of the pinned digests it
      # ships, so a copy that drifts from the table pins something else.
      - name: Check the clients ship the pinned release digests
        run: python3 scripts/sync-release-digests.py --check

      - name: Download binary artifacts
        uses: actions/download-artifact@v4
        with:
          name: binaries
          path: bin

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install sysml-grpc
        run: |
          mkdir -p ~/.opensysml/bin
          cp bin/sysml-grpc ~/.opensysml/bin/
          chmod +x ~/.opensysml/bin/sysml-grpc

      # The verification-questions tests ask the service solver-backed questions;
      # the solver is an external process the service finds on PATH.
      - name: Install Z3
        run: |
          sudo apt-get update
          sudo apt-get install -y z3
          z3 --version

      - name: Install Python client
        run: |
          make python-install
          # Pinned and wheel-only: an unpinned resolve runs whatever was
          # published today, and a source distribution runs its own build code.
          pip install --only-binary :all: pytest==9.0.3 pytest-mock==3.15.1 psutil==7.2.2 fmpy==0.3.32 mypy==2.4.0 types-protobuf==7.35.1.20260906 'pyright[nodejs]==1.1.414'

      # The FMI runner test's FMUs, same pin as the Go gate's.
      - name: Cache the Reference-FMUs
        uses: actions/cache@v4
        with:
          path: examples/reference-fmus
          key: reference-fmus-${{ hashFiles('scripts/download-reference-fmus.sh', 'scripts/reference-fmus-pin.sh') }}

      - name: Download the Reference-FMUs
        run: ./scripts/download-reference-fmus.sh

      # The integration tests connect to a service on the standard port with
      # auto_start=False, the explicit opt-in to one the client does not manage;
      # without it they skip, exercising nothing, so one runs here for the rest of
      # the job. Tests naming no address start a private child of their own.
      - name: Start sysml-grpc
        run: nohup ~/.opensysml/bin/sysml-grpc -port 50051 > /tmp/sysml-grpc.log 2>&1 &

      - name: Wait for sysml-grpc
        run: |
          python3 - <<'PY'
          import socket, sys, time

          for _ in range(30):
              with socket.socket() as probe:
                  probe.settimeout(1)
                  if probe.connect_ex(("localhost", 50051)) == 0:
                      print("sysml-grpc is listening on 50051")
                      sys.exit(0)
              time.sleep(1)
          sys.exit("sysml-grpc never listened on 50051")
          PY

      # OPENSYSML_REQUIRE_SERVICE turns "no service, so skip" into a failure: a
      # service is provided here, so its absence is the bug, not a pass.
      - name: Run Python client tests
        env:
          OPENSYSML_REQUIRE_SERVICE: 1
          OPENSYSML_REQUIRE_TYPECHECKERS: 1
        run: make python-test

      - name: Verify Python client import
        run: python3 -c "import opensysml; print(f'opensysml {opensysml.__version__} imported successfully')"

      # Pinned by digest, so a substituted asset is not run.
      - name: Install buf
        run: |
          curl -fsSL --proto '=https' --proto-redir '=https' -o /tmp/buf \
            https://github.com/bufbuild/buf/releases/download/v1.57.2/buf-Linux-x86_64
          echo "644e6fa4a62afc2b0d425d3ac9538d2f512947c0f2e82fc95c41a5eab6729414  /tmp/buf" | sha256sum --check --strict
          sudo install -m 0755 /tmp/buf /usr/local/bin/buf
          buf --version

      # Committed stubs must be what buf generates, or the checked-in client and
      # the schema can drift apart silently.
      - name: Verify the committed Python stubs are current
        run: |
          # Pinned to the version recorded in the committed stubs
          # (GRPC_GENERATED_VERSION), so a newer release cannot fail this check.
          pip install --only-binary :all: grpcio-tools==1.83.0
          make python-proto BUF=buf
          git add -N client/python/opensysml/proto
          git diff --exit-code client/python/opensysml/proto

  rust-test:
    name: Rust client tests
    needs: [changes, build]
    if: needs.changes.outputs.rust == 'true'
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v4

      # The client verifies a download against the copy of the pinned digests it
      # ships, so a copy that drifts from the table pins something else.
      - name: Check the clients ship the pinned release digests
        run: python3 scripts/sync-release-digests.py --check

      # Reuse the service built by the Go job rather than installing Go again
      # in this Rust-focused gate.
      - uses: actions/download-artifact@v4
        with:
          name: binaries
          path: bin

      # The artifact is a zip, which does not carry the executable bit.
      - name: Install the sysml-grpc binary
        run: chmod +x bin/sysml-grpc

      - name: Install Rust 1.83
        run: |
          rustup toolchain install 1.83.0 --profile minimal
          rustup default 1.83.0
          rustup component add rustfmt clippy --toolchain 1.83.0
          rustc --version
          cargo --version

      - name: Check Rust formatting
        working-directory: client/rust
        run: cargo fmt --all -- --check

      - name: Run Rust clippy
        working-directory: client/rust
        run: cargo clippy --all-targets -- -D warnings

      # A missing service must fail rather than silently skipping integration
      # tests, because the downloaded binary is required by this job.
      - name: Run Rust tests
        working-directory: client/rust
        env:
          OPENSYSML_GRPC_BINARY: ${{ github.workspace }}/bin/sysml-grpc
          OPENSYSML_REQUIRE_SERVICE: 1
        run: cargo test --workspace

      # Invoke the runner directly so this job does not rebuild the service
      # through make conformance-rust, which would require Go here.
      - name: Run Rust conformance
        env:
          OPENSYSML_GRPC_BINARY: ${{ github.workspace }}/bin/sysml-grpc
        run: |
          cargo run --manifest-path client/rust/Cargo.toml -p opensysml-conformance -- \
            -binary "$GITHUB_WORKSPACE/bin/sysml-grpc" \
            -report bin/conformance-report-rust.json

      - name: Package Rust client
        working-directory: client/rust
        run: cargo package -p opensysml

      # The digest pins the generator binary so a substituted release cannot
      # change the committed Rust artifacts.
      - name: Install buf
        run: |
          curl -fsSL --proto '=https' --proto-redir '=https' -o /tmp/buf \
            https://github.com/bufbuild/buf/releases/download/v1.57.2/buf-Linux-x86_64
          echo "644e6fa4a62afc2b0d425d3ac9538d2f512947c0f2e82fc95c41a5eab6729414  /tmp/buf" | sha256sum --check --strict
          chmod +x /tmp/buf
          /tmp/buf --version

      - name: Verify Rust generated artifacts
        run: |
          make BUF=/tmp/buf proto-rust
          git add -N client/rust/opensysml/src/proto client/rust/conformance/sysml.descriptor.binpb
          git diff --exit-code client/rust/opensysml/src/proto client/rust/conformance/sysml.descriptor.binpb

      - uses: actions/upload-artifact@v4
        with:
          name: conformance-report-rust
          path: bin/conformance-report-rust.json

  # Mirrors the CircleCI julia-client job: Pkg.test on the two supported Julia
  # versions plus the conformance suite, against the binary the build job made.
  julia-client:
    name: Julia client tests
    needs: [changes, build]
    if: needs.changes.outputs.julia == 'true'
    runs-on: ubuntu-latest
    permissions:
      contents: read
    strategy:
      matrix:
        julia-version: ['1.10', 'lts']
    steps:
      - uses: actions/checkout@v4

      - uses: actions/download-artifact@v4
        with:
          name: binaries
          path: bin

      # The artifact is a zip, which does not carry the executable bit.
      - name: Install the sysml-grpc binary
        run: chmod +x bin/sysml-grpc

      - name: Set up Julia ${{ matrix.julia-version }}
        uses: julia-actions/setup-julia@4c0cb0fce8556fdb04a90347310e5db8b1f98fb9 # v2.7.0
        with:
          version: ${{ matrix.julia-version }}

      - name: Run Julia tests
        working-directory: client/julia/OpenSysML
        env:
          OPENSYSML_GRPC_BINARY: ${{ github.workspace }}/bin/sysml-grpc
        run: julia --project=. -e 'using Pkg; Pkg.test()'

      - name: Run Julia conformance
        env:
          OPENSYSML_GRPC_BINARY: ${{ github.workspace }}/bin/sysml-grpc
        run: |
          julia --project=client/julia/OpenSysML client/julia/OpenSysML/conformance/run.jl \
            --binary "$GITHUB_WORKSPACE/bin/sysml-grpc" \
            --report bin/conformance-report-julia.json

      - uses: actions/upload-artifact@v4
        with:
          name: conformance-report-julia-${{ matrix.julia-version }}
          path: bin/conformance-report-julia.json

  # Mirrors the CircleCI matlab-client job: the tests and the conformance suite
  # under GNU Octave — MATLAB itself is not available in CI, and its
  # matlab.net.http path is exercised by no gate. The CI build of Octave is
  # built without Java, so the private-child path cannot run there: the job
  # starts a service itself and hands the runner its address.
  matlab-client:
    name: MATLAB/Octave client tests
    needs: [changes, build]
    if: needs.changes.outputs.matlab == 'true'
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v4

      - uses: actions/download-artifact@v4
        with:
          name: binaries
          path: bin

      # The artifact is a zip, which does not carry the executable bit.
      - name: Install the sysml-grpc binary
        run: chmod +x bin/sysml-grpc

      - name: Install GNU Octave
        run: |
          sudo apt-get update
          sudo apt-get install -y octave

      - name: Start sysml-grpc
        run: |
          bin/sysml-grpc -port 0 -health-port 0 -report-address > bin/octave-svc-addr &
          svc_pid=$!
          echo "svc_pid=$svc_pid" >> "$GITHUB_ENV"
          for i in $(seq 1 100); do [ -s bin/octave-svc-addr ] && break; sleep 0.1; done
          test -s bin/octave-svc-addr

      - name: Run MATLAB client tests
        working-directory: client/matlab/tests
        run: |
          addr=$(cat "$GITHUB_WORKSPACE/bin/octave-svc-addr")
          OPENSYSML_SERVICE="$addr" octave --no-gui --eval "run_tests"

      - name: Run MATLAB conformance
        run: |
          addr=$(cat "$GITHUB_WORKSPACE/bin/octave-svc-addr")
          octave --no-gui --eval "addpath('client/matlab'); addpath('client/matlab/conformance'); addpath('client/matlab/conformance/private'); run_conformance('--address','$addr','--report','bin/conformance-report-matlab.json')"

      - name: Stop sysml-grpc
        if: always()
        run: kill "$svc_pid" 2>/dev/null || true

      - uses: actions/upload-artifact@v4
        with:
          name: conformance-report-matlab
          path: bin/conformance-report-matlab.json

  # Mirrors the CircleCI java-test job: unit tests plus the conformance suite over
  # both Connect encodings, on the client's Java 17 baseline.
  java-test:
    name: Java client tests
    needs: [changes, build]
    if: needs.changes.outputs.java == 'true'
    runs-on: ubuntu-latest
    permissions:
      contents: read
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v4

      # The client verifies a download against the copy of the pinned digests it
      # ships, so a copy that drifts from the table pins something else.
      - name: Check the clients ship the pinned release digests
        run: python3 scripts/sync-release-digests.py --check

      - uses: actions/download-artifact@v4
        with:
          name: binaries
          path: bin

      # 17 is the client's compile target, so a 21-only construct fails here.
      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: '17'
          cache: maven

      - name: Make the service binary executable
        run: chmod +x bin/sysml-grpc

      # opensysml.requireService turns "no binary, so skip" into a failure, and
      # `install` builds the sources and javadoc jars a release needs on every commit.
      - name: Test and install the client
        run: mvn -B -f client/java/pom.xml install -Dopensysml.requireService=true

      - name: Run the conformance suite through the client
        run: |
          mvn -B -q -f client/java/pom.xml -pl opensysml-conformance \
            dependency:build-classpath -Dmdep.outputFile=/tmp/cp.txt
          java -cp "client/java/opensysml-conformance/target/classes:$(cat /tmp/cp.txt)" \
            org.openmbee.opensysml.conformance.Main \
            -binary bin/sysml-grpc -protocols connect,connect-json -allow-skips \
            -report conformance-report-java.json

      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: java-conformance-report
          path: conformance-report-java.json

      # The Java message classes come out of the one buf template that also runs the
      # Go plugins through `go run`, so the check needs a Go toolchain even here.
      - uses: actions/setup-go@v5
        with:
          go-version-file: go.mod
          cache: true

      # Pinned by digest, so a substituted asset is not run.
      - name: Install buf
        run: |
          curl -fsSL --proto '=https' --proto-redir '=https' -o /tmp/buf \
            https://github.com/bufbuild/buf/releases/download/v1.57.2/buf-Linux-x86_64
          echo "644e6fa4a62afc2b0d425d3ac9538d2f512947c0f2e82fc95c41a5eab6729414  /tmp/buf" | sha256sum --check --strict
          sudo install -m 0755 /tmp/buf /usr/local/bin/buf
          buf --version

      # Committed stubs must be what buf generates, or the checked-in client and
      # the schema can drift apart silently.
      - name: Verify the committed Java stubs are current
        run: |
          make proto-buf BUF=buf
          git add -N client/java/opensysml-client/src/main/java/org/openmbee/opensysml/proto
          git diff --exit-code client/java/opensysml-client/src/main/java/org/openmbee/opensysml/proto

  syson-plugin:
    name: SysON plugin
    needs: [changes, build]
    if: needs.changes.outputs.syson == 'true'
    runs-on: ubuntu-latest
    permissions:
      contents: read
    timeout-minutes: 20
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Download binary artifacts
        uses: actions/download-artifact@v4
        with:
          name: binaries
          path: bin

      - name: Make the service binary executable
        run: chmod +x bin/sysml-grpc

      # SysON 2026.9.2 runs on 21; the module compiles at release 17.
      - name: Set up Java
        uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: '21'
          cache: maven

      - name: Install the client dependency
        run: mvn -B -q -f client/java/pom.xml install -DskipTests -Dmaven.javadoc.skip=true

      - name: Test and install the SysON backend
        run: mvn -B -f editors/syson/pom.xml install -Dopensysml.requireService=true

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '24'
          cache: npm
          cache-dependency-path: editors/syson/frontend/package-lock.json

      - name: Build and test the SysON frontend
        working-directory: editors/syson/frontend
        run: |
          npm ci --ignore-scripts
          npm run typecheck
          npm run format:check
          npm test
          npm run build

  conformance-pkg:
    name: Conformance suite
    needs: changes
    if: needs.changes.outputs.go == 'true'
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-go@v5
        with:
          go-version-file: go.mod
          cache: true

      - name: Download modules
        run: go mod download

      # The runner builds and starts sysml-grpc itself, so this gate proves the
      # whole path a client takes, not a pre-started service.
      - name: Run conformance suite
        run: make conformance

      # The same suite against the legacy grpc-go transport, so -transport grpc
      # cannot rot untested.
      - name: Run conformance suite against -transport grpc
        run: go run -C tools ./cmd/conformance -transport grpc -protocols grpc -report bin/conformance-grpc-transport-report.json

      # The same suite through the public Go API (client/opensysml); the pkg
      # protocol runs in-process and pkg-connect dials the service, so this proves
      # the API answers as the wire does. Scenarios outside its v1 surface are
      # counted skips, not hidden.
      - name: Conformance suite through client/opensysml
        run: make conformance-pkg

      # if: always() — the reports matter most when a gate failed and halted the job.
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: conformance-reports
          path: |
            bin/conformance-report.json
            bin/conformance-report.xml
            bin/conformance-grpc-transport-report.json
            bin/conformance-pkg-report.json