docs-visual.yml

name: Python documentation visual evidence

on:
  workflow_call:
    inputs:
      source_base_sha:
        description: Candidate comparison revision; an unavailable revision fails safe to all tracked files.
        required: false
        type: string
      source_ref:
        description: Immutable candidate revision; the calling workflow's commit is the default.
        required: false
        type: string

permissions:
  contents: read

jobs:
  visual-evidence:
    if: github.api_url == 'https://api.github.com'
    runs-on: ubuntu-latest
    timeout-minutes: 20
    steps:
      - name: Check out candidate source
        uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803  # v6
        with:
          fetch-depth: 0
          path: candidate
          persist-credentials: false
          ref: ${{ inputs.source_ref || github.sha }}
          repository: ${{ github.repository }}

      - name: Check out visual evidence controller
        uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803  # v6
        with:
          path: visual-controller
          persist-credentials: false
          ref: 0421c2e3a78ba4ca2adfe118e57db88d2264a62b
          repository: durable-workflow/.github

      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1  # v6
        with:
          python-version: "3.12"

      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38  # v6
        with:
          node-version: "24"

      - name: Classify candidate changes
        id: classify
        env:
          SOURCE_BASE_SHA: ${{ inputs.source_base_sha }}
          SOURCE_REPOSITORY: ${{ github.repository }}
        run: |
          test "$SOURCE_REPOSITORY" = durable-workflow/sdk-python
          classification_args=(
            --root "$GITHUB_WORKSPACE/candidate"
            --github-output "$GITHUB_OUTPUT"
          )
          if [[ "$SOURCE_BASE_SHA" =~ ^[0-9a-f]{40}$ ]] && \
            git -C candidate cat-file -e "${SOURCE_BASE_SHA}^{commit}" 2>/dev/null; then
            classification_args+=(--base-ref "$SOURCE_BASE_SHA")
          else
            mapfile -d '' candidate_files < <(git -C candidate ls-files -z)
            for candidate_file in "${candidate_files[@]}"; do
              classification_args+=(--changed-file "$candidate_file")
            done
          fi
          printf 'source_revision=%s\n' "$(git -C candidate rev-parse HEAD)" >> "$GITHUB_OUTPUT"
          python candidate/scripts/ci/classify_docs_visual_changes.py \
            "${classification_args[@]}" > visual-classification.json

      - name: Install documentation dependencies
        if: steps.classify.outputs.required == 'true'
        working-directory: candidate
        run: pip install -e '.[docs]'

      - name: Install browser for navigation interaction checks
        if: steps.classify.outputs.required == 'true'
        run: python -m playwright install --with-deps chromium

      - name: Install pinned visual capture runtime
        if: steps.classify.outputs.required == 'true'
        run: npm ci --prefix visual-controller

      - name: Build candidate reference
        if: steps.classify.outputs.required == 'true'
        working-directory: candidate
        run: |
          mkdocs build --strict
          python scripts/check-docs-analytics.py site

      - name: Verify responsive navigation breakpoint transition
        if: steps.classify.outputs.required == 'true' && steps.classify.outputs.navigation == 'true'
        run: |
          mkdir -p visual-review
          python candidate/scripts/check-docs-layout.py candidate/site \
            --navigation-transition-only \
            --transition-evidence visual-review/navigation-breakpoint-transition.json

      - name: Verify nested reference navigation reachability
        if: steps.classify.outputs.required == 'true'
        env:
          SOURCE_REVISION: ${{ steps.classify.outputs.source_revision }}
        run: |
          mkdir -p visual-review
          python candidate/scripts/check-docs-layout.py candidate/site \
            --nested-navigation-only \
            --nested-navigation-evidence visual-review/nested-navigation-keyboard.json \
            --source-revision "$SOURCE_REVISION"

      - name: Capture candidate interaction states
        if: steps.classify.outputs.required == 'true'
        env:
          NAVIGATION_REQUIRED: ${{ steps.classify.outputs.navigation }}
          SEARCH_REQUIRED: ${{ steps.classify.outputs.search }}
          SOURCE_REVISION: ${{ steps.classify.outputs.source_revision }}
          TMPDIR: ${{ runner.temp }}/python-docs-visual-${{ github.run_id }}-${{ github.run_attempt }}
        run: |
          mkdir -p "$TMPDIR" visual-review
          cp visual-classification.json visual-review/classification.json
          python3 -m http.server 4173 --bind 127.0.0.1 --directory candidate/site \
            >"$RUNNER_TEMP/python-docs-preview.log" 2>&1 &
          preview_pid=$!
          trap 'kill "$preview_pid" 2>/dev/null || true' EXIT
          python - <<'PY'
          import time
          import urllib.request

          for _ in range(50):
              try:
                  with urllib.request.urlopen("http://127.0.0.1:4173/", timeout=1) as response:
                      if response.status == 200:
                          break
              except OSError:
                  time.sleep(0.1)
          else:
              raise SystemExit("candidate documentation preview did not become ready")
          PY
          capture() {
            local state=$1 width=$2 height=$3
            shift 3
            local capture_args=()
            local capture_url=http://127.0.0.1:4173/
            if [ "$width" = 640 ] && [ "$height" = 360 ] && [ "$state" = default ]; then
              capture_args+=(--full-page)
            fi
            if [ "$state" = search-populated ]; then
              capture_url="${capture_url}?q=workflow"
            fi
            node visual-controller/scripts/pipeline_visual_capture.mjs \
              --url "$capture_url" \
              --surface python-sdk-reference --state "$state" \
              --width "$width" --height "$height" \
              --source-repository durable-workflow/sdk-python \
              --source-revision "$SOURCE_REVISION" \
              --screenshot "visual-review/${state}-${width}x${height}.png" \
              --report "visual-review/${state}-${width}x${height}.json" \
              --manifest visual-review/manifest.json "${capture_args[@]}" "$@"
          }
          capture_nested() {
            local route=$1 position=$2 state=$3 width=$4 height=$5
            shift 5
            local capture_args=()
            if [ "$width" = 640 ] && [ "$height" = 360 ] && [ "$state" = default ]; then
              capture_args+=(--full-page)
            fi
            node visual-controller/scripts/pipeline_visual_capture.mjs \
              --url "http://127.0.0.1:4173/reference/$route/" \
              --surface "python-sdk-$route-reference" --state "$state" \
              --width "$width" --height "$height" \
              --source-repository durable-workflow/sdk-python \
              --source-revision "$SOURCE_REVISION" \
              --screenshot "visual-review/nested-${position}-${route}-${state}-${width}x${height}.png" \
              --report "visual-review/nested-${position}-${route}-${state}-${width}x${height}.json" \
              --manifest visual-review/manifest.json "${capture_args[@]}" "$@"
          }
          for viewport in 1440x920 768x1024 390x844 640x360; do
            width=${viewport%x*}
            height=${viewport#*x}
            capture default "$width" "$height"
            if [ "$NAVIGATION_REQUIRED" = true ] && [ "$width" -lt 960 ]; then
              capture navigation-open "$width" "$height" \
                --state-scope responsive \
                --click ".md-header__button[for='__drawer']"
            fi
            for reference in first:client middle:serializer final:testing; do
              position=${reference%%:*}
              route=${reference#*:}
              capture_nested "$route" "$position" default "$width" "$height"
              if [ "$width" -lt 960 ]; then
                capture_nested "$route" "$position" navigation-open "$width" "$height" \
                  --state-scope responsive \
                  --click ".md-header__button[for='__drawer']"
              fi
            done
            if [ "$SEARCH_REQUIRED" = true ]; then
              if [ "$width" -ge 960 ]; then
                search_selector=.md-search__input
              else
                search_selector=".md-header__button[for='__search']"
              fi
              capture search-open "$width" "$height" --click "$search_selector"
              capture search-populated "$width" "$height"
            fi
          done
          python - <<'PY'
          import json
          import os
          from pathlib import Path
          from urllib.parse import urlsplit

          evidence_root = Path("visual-review")
          keyboard_path = evidence_root / "nested-navigation-keyboard.json"
          keyboard = json.loads(keyboard_path.read_text(encoding="utf-8"))
          expected_source = {
              "repository": "durable-workflow/sdk-python",
              "revision": os.environ["SOURCE_REVISION"],
          }
          expected_routes = {
              "/reference/client/": {
                  "active": "Client",
                  "position": "first",
                  "surface": "python-sdk-client-reference",
              },
              "/reference/serializer/": {
                  "active": "Serializer",
                  "position": "middle",
                  "surface": "python-sdk-serializer-reference",
              },
              "/reference/testing/": {
                  "active": "Testing",
                  "position": "final",
                  "surface": "python-sdk-testing-reference",
              },
          }

          def validate_reference_panel(panel, expected_active, label):
              if not isinstance(panel, dict):
                  raise ValueError(f"{label} has no measured reference panel")
              try:
                  active = panel["active"]
                  drawer = panel["drawer"]
                  reference_list = panel["list"]
                  active_top = float(active["top"])
                  active_bottom = float(active["bottom"])
                  list_top = float(reference_list["top"])
                  list_bottom = float(reference_list["bottom"])
                  drawer_bottom = float(drawer["bottom"])
                  client_height = float(reference_list["clientHeight"])
              except (KeyError, TypeError, ValueError) as error:
                  raise ValueError(f"{label} has malformed reference panel geometry") from error
              if active.get("text") != expected_active:
                  raise ValueError(f"{label} does not identify its active destination")
              if active_top < list_top - 1 or active_bottom > list_bottom + 1:
                  raise ValueError(f"{label} clips its active destination")
              if abs(list_bottom - drawer_bottom) > 1 or client_height < 200:
                  raise ValueError(f"{label} does not use the available drawer height")
              if reference_list.get("overflowY") != "auto":
                  raise ValueError(f"{label} does not expose the qualified nested-list viewport")

          if (
              keyboard.get("schema") != "durable-workflow.python-docs.nested-navigation/v3"
              or keyboard.get("outcome") != "pass"
              or set(keyboard.get("routes", [])) != set(expected_routes)
          ):
              raise SystemExit("nested reference keyboard evidence did not qualify the required route positions")
          if keyboard.get("source") != expected_source:
              raise SystemExit("nested reference keyboard evidence is not bound to the captured source")
          regression = keyboard.get("regression", {})
          three_row_fixture = regression.get("three_row_list", {})
          if (
              three_row_fixture.get("visible_rows") != 3
              or three_row_fixture.get("geometry") != "affected fixture rejected"
              or three_row_fixture.get("interaction") != "affected fixture rejected"
          ):
              raise SystemExit("nested reference evidence did not exercise the three-row clipped-list fixture")
          try:
              validate_reference_panel(
                  three_row_fixture.get("reference_panel"),
                  expected_routes["/reference/testing/"]["active"],
                  "three-row clipped-list fixture",
              )
          except ValueError:
              pass
          else:
              raise SystemExit("retained visual-evidence validation accepted the three-row clipped-list fixture")
          keyboard_viewports = {
              (entry["route"], entry["viewport"]["width"], entry["viewport"]["height"]): entry
              for entry in keyboard.get("viewports", [])
          }

          reports = sorted(Path("visual-review").glob("nested-*-*x*.json"))
          if len(reports) != 21:
              raise SystemExit(f"nested reference evidence is incomplete: {[path.name for path in reports]}")
          viewport_states = (
              (1440, 920, "default"),
              (768, 1024, "default"),
              (768, 1024, "navigation-open"),
              (390, 844, "default"),
              (390, 844, "navigation-open"),
              (640, 360, "default"),
              (640, 360, "navigation-open"),
          )
          expected_states = {
              (route, width, height, state)
              for route in expected_routes
              for width, height, state in viewport_states
          }
          observed_states = set()
          qualified_states = []
          for report in reports:
              captured = json.loads(report.read_text(encoding="utf-8"))
              state = captured.get("state")
              viewport = captured.get("viewport", {})
              viewport_key = (viewport.get("width"), viewport.get("height"))
              page_route = urlsplit(captured.get("page_url", "")).path
              route_contract = expected_routes.get(page_route)
              expected_full_page = viewport_key == (640, 360) and state == "default"
              if (
                  route_contract is None
                  or captured.get("surface") != route_contract["surface"]
                  or captured.get("source") != expected_source
                  or captured.get("full_page") is not expected_full_page
              ):
                  raise SystemExit(f"{report.name} is not a faithful source-bound nested viewport capture")
              keyboard_entry = keyboard_viewports.get((page_route, *viewport_key), {})
              if keyboard_entry.get("position") != route_contract["position"]:
                  raise SystemExit(f"{report.name} does not match its required route position")
              keyboard_state = keyboard_entry.get("states", {}).get(state)
              if keyboard_state is None:
                  raise SystemExit(f"{report.name} has no matching keyboard state evidence")
              if keyboard_state.get("pointer_unreachable") != 0:
                  raise SystemExit(f"{report.name} keyboard fixture reported unreachable pointer controls")
              active_keyboard_controls = keyboard_state.get("active_keyboard_controls")
              if state == "navigation-open" and not active_keyboard_controls:
                  raise SystemExit(f"{report.name} has no active drawer keyboard traversal evidence")
              reference_panel = keyboard_state.get("reference_panel")
              if state == "navigation-open":
                  try:
                      validate_reference_panel(
                          reference_panel,
                          route_contract["active"],
                          report.name,
                      )
                  except ValueError as error:
                      raise SystemExit(str(error)) from error
              geometry = captured["geometry"]
              if geometry["unreachable_controls"]:
                  raise SystemExit(
                      f"{report.name} has unreachable controls: {geometry['unreachable_controls']}"
                  )
              if state == "navigation-open" and geometry.get("interactive_control_count") != len(
                  active_keyboard_controls
              ):
                  raise SystemExit(f"{report.name} pointer and keyboard control sets do not match")
              observed_states.add((page_route, *viewport_key, state))
              qualified_states.append(
                  {
                      "capture_report": report.name,
                      "position": route_contract["position"],
                      "route": page_route,
                      "state": state,
                      "viewport": viewport,
                      "full_page": captured["full_page"],
                      "pointer_unreachable_controls": geometry["unreachable_controls"],
                      "active_keyboard_controls": active_keyboard_controls or [],
                      "reference_panel": reference_panel,
                  }
              )
          if observed_states != expected_states:
              raise SystemExit(f"nested reference state matrix does not match: {sorted(observed_states)}")

          qualification = {
              "schema": "durable-workflow.python-docs.nested-navigation-qualification/v3",
              "outcome": "pass",
              "source": expected_source,
              "routes": list(expected_routes),
              "states": qualified_states,
              "regression": regression,
          }
          (evidence_root / "nested-navigation-qualification.json").write_text(
              f"{json.dumps(qualification, indent=2)}\n",
              encoding="utf-8",
          )
          PY

      - name: Validate candidate evidence
        if: steps.classify.outputs.required == 'true'
        env:
          SEARCH_REQUIRED: ${{ steps.classify.outputs.search }}
        run: |
          classification_root="$RUNNER_TEMP/python-docs-visual-classification"
          mkdir -p "$classification_root"
          validation_args=(
            --root "$classification_root"
            --manifest "$GITHUB_WORKSPACE/visual-review/manifest.json"
          )
          printf '%s\n' '.documentation-surface { display: block; }' \
            > "$classification_root/documentation.css"
          validation_args+=(--changed-file documentation.css)
          if [ "$SEARCH_REQUIRED" = true ]; then
            printf '%s\n' '<button data-md-toggle="search">Search</button>' \
              > "$classification_root/search.html"
            validation_args+=(--changed-file search.html)
          fi
          python visual-controller/scripts/visual_evidence.py validate "${validation_args[@]}"

      - name: Retain candidate visual evidence
        if: always() && steps.classify.outputs.required == 'true'
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7
        with:
          if-no-files-found: error
          name: python-docs-visual-${{ steps.classify.outputs.source_revision }}
          path: visual-review
          retention-days: 30