open-standards/.github/workflows/wai-quantum-docs.yml

name: wai-quantum docs, course and locales

# The WAI Quantum documentation, the circuits course and the translations:
#   - docs: wai/tools/quantum-docs/ci.sh builds the command line, the job service and
#     the Python package from this checkout, starts a service, and runs check_docs.py
#     over every page docs.json names (the READMEs and docs pages of the engine, the
#     command line, the service, Python, the Studio, the desktop app, the editors and
#     the providers, the course's lessons, the agent skill, and their translations):
#     every block marked runnable run, every shown output held to the real one, every
#     receipt a block writes verified, the Rust blocks built and run, every block that
#     cannot run checked for the commands and flags it names, every `wai-quantum …` in
#     the prose a real command, every relative link a file, every dependency shown one
#     this repository's version satisfies, and every translation holding its English
#     page's code;
#   - course: engine::course's tests (every lesson's solution passes its own exercise
#     by proof or evidence, every known wrong answer fails it for its stated reason,
#     no hint or lesson gives the solution, every locale has every text and message)
#     and the command line's course and locale tests, each required by name;
#   - locales: every key of the Studio's words in every locale, with the same
#     placeholders, each translation marked machine-assisted (no browser).
# The Studio's course in the browser, in both languages, is in wai-quantum-studio.yml.

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

on:
  push:
    branches: [main]
    paths:
      - 'wai/wai-quantum/**'
      - 'wai/wai-quantum-cli/**'
      - 'wai/wai-quantum-service/**'
      - 'wai/wai-quantum-py/**'
      - 'wai/wai-quantum-qpu/**'
      - 'wai/wai-quantum-desktop/README.md'
      - 'wai/quantum-studio/**'
      - 'wai/tools/wai-quantum-editor/README.md'
      - 'wai/tools/quantum-docs/**'
      - 'wai/CHANGELOG.md'
      - 'rust-toolchain.toml'
      - '.github/workflows/wai-quantum-docs.yml'
  pull_request:
    paths:
      - 'wai/wai-quantum/**'
      - 'wai/wai-quantum-cli/**'
      - 'wai/wai-quantum-service/**'
      - 'wai/wai-quantum-py/**'
      - 'wai/wai-quantum-qpu/**'
      - 'wai/wai-quantum-desktop/README.md'
      - 'wai/quantum-studio/**'
      - 'wai/tools/wai-quantum-editor/README.md'
      - 'wai/tools/quantum-docs/**'
      - 'wai/CHANGELOG.md'
      - 'rust-toolchain.toml'
      - '.github/workflows/wai-quantum-docs.yml'

jobs:
  relevant:
    name: does this change touch it
    runs-on: linux
    outputs:
      run: ${{ steps.gate.outputs.run }}
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0
      - id: gate
        run: |
          set -euo pipefail
          r=$(python3 scripts/pr-touches-paths.py .github/workflows/wai-quantum-docs.yml \
                "${{ github.event.pull_request.base.sha }}" \
                "${{ github.event.pull_request.head.sha }}")
          echo "this change touches the docs, the course or the locales: $r"
          echo "run=$r" >> "$GITHUB_OUTPUT"

  docs:
    name: every command and snippet in the docs · linux
    needs: relevant
    if: needs.relevant.outputs.run == 'true'
    runs-on: linux
    timeout-minutes: 180
    steps:
      - uses: actions/checkout@v5
      - name: Install Rust 1.98.0, and uv
        shell: bash
        run: |
          export PATH="$HOME/.local/bin:$HOME/.cargo/bin:$PATH"
          command -v rustup >/dev/null 2>&1 || \
            curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --profile minimal --default-toolchain 1.98.0
          rustup toolchain install 1.98.0 --profile minimal
          rustup default 1.98.0
          command -v uv >/dev/null 2>&1 || curl -LsSf https://astral.sh/uv/install.sh | sh
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
          echo "$HOME/.cargo/bin" >> "$GITHUB_PATH"
      - name: Build, start a service, and run every page
        shell: bash
        run: |
          set -euo pipefail
          bash wai/tools/quantum-docs/ci.sh 2>&1 | tee "$RUNNER_TEMP/docs.log"
          grep -q '^every check passed$' "$RUNNER_TEMP/docs.log" || { echo "::error::a page's check failed"; exit 1; }

  course:
    name: the course and the command line's languages · linux
    needs: relevant
    if: needs.relevant.outputs.run == 'true'
    runs-on: linux
    timeout-minutes: 60
    steps:
      - uses: actions/checkout@v5
      - name: Install Rust 1.98.0
        shell: bash
        run: |
          export PATH="$HOME/.cargo/bin:$PATH"
          command -v rustup >/dev/null 2>&1 || \
            curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --profile minimal --default-toolchain 1.98.0
          rustup toolchain install 1.98.0 --profile minimal
          rustup default 1.98.0
          echo "$HOME/.cargo/bin" >> "$GITHUB_PATH"
      # A module filter is satisfied by any one test of the module, so each test is
      # required by name to have run.
      - name: Every solution passes, every wrong answer fails, every locale is whole
        shell: bash
        working-directory: wai/wai-quantum
        run: |
          set -euo pipefail
          cargo test --locked --release --features full --lib -- engine::course:: 2>&1 | tee "$RUNNER_TEMP/course.log"
          grep -qE '^test result: ok\. 9 passed; 0 failed' "$RUNNER_TEMP/course.log" || { echo "::error::the course's tests did not all pass"; exit 1; }
          for t in every_solution_passes_its_exercise_and_every_known_wrong_answer_fails_it \
                   a_check_says_what_went_wrong_from_the_engine_and_never_shows_the_solution \
                   no_hint_or_lesson_gives_the_solution \
                   every_locale_has_every_text_and_every_message \
                   the_course_reads_and_every_lesson_is_in_one_unit_with_its_files \
                   the_schemas_name_the_fields_the_reader_takes \
                   a_check_is_the_same_bytes_every_time \
                   the_estimate_lesson_prices_the_program \
                   a_locale_tag_picks_the_course_s_locale; do
            grep -q "^test engine::course::tests::$t \.\.\. ok$" "$RUNNER_TEMP/course.log" || { echo "::error::$t did not run"; exit 1; }
          done
      - name: The command line's course and its languages
        shell: bash
        working-directory: wai/wai-quantum-cli
        run: |
          set -euo pipefail
          cargo test --locked --release --bin wai-quantum -- locale:: learn:: 2>&1 | tee "$RUNNER_TEMP/cli.log"
          for t in locale::tests::the_language_is_lang_else_the_environment_s \
                   locale::tests::every_key_exists_in_every_locale_and_every_summary_is_translated_from_today_s_english \
                   locale::tests::a_label_is_padded_by_its_width_on_a_terminal \
                   learn::tests::progress_is_kept_in_one_file_and_marks_a_pass_once; do
            grep -q "^test $t \.\.\. ok$" "$RUNNER_TEMP/cli.log" || { echo "::error::$t did not run"; exit 1; }
          done

  locales:
    name: the Studio's words in every locale · linux
    needs: relevant
    if: needs.relevant.outputs.run == 'true'
    runs-on: linux
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - name: Every key in every locale, with its placeholders
        shell: bash
        working-directory: wai/quantum-studio
        run: |
          set -euo pipefail
          node test/locales.test.mjs | tee "$RUNNER_TEMP/locales.log"
          grep -q '^every check passed$' "$RUNNER_TEMP/locales.log" || { echo "::error::a locale is missing a key"; exit 1; }