ci.yml

name: CI

on:
  push:
    branches: [main]
  pull_request:

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

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
          cache: pip

      - name: Install
        # setup-python ships the pip bundled with each interpreter (24.0 on 3.11,
        # 25.0.1 on 3.12); PEP 735 `--group` needs 25.1+.
        run: |
          python -m pip install --upgrade pip
          pip install -e . --group dev

      - name: Lint
        run: |
          ruff check .
          ruff format --check .
          shellcheck scripts/scheduler/*.sh

      - name: Offline benchmark check
        # Synthetic fixture only: this guards limiter/telemetry regressions and
        # deliberately makes no claim about vendor speed or availability.
        run: python scripts/dev/benchmark_offline.py --check --max-elapsed-seconds 10 --max-concurrency 2

      - name: Generated docs in sync
        # Schema column tables, the example config mirror, the derivative
        # capability table and both CLI references are mirrors of code. The
        # schema page is synced rather than generated: its prose is
        # hand-written and only the column tables are kept honest here.
        run: python scripts/dev/sync_docs.py --check

      - name: Public package boundary
        run: |
          python -m pip install build
          python -m build --sdist --wheel
          python scripts/dev/check_public_package.py dist/*.whl dist/*.tar.gz

      - uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: npm
          cache-dependency-path: frontend/package-lock.json

      - name: Check dashboard bundle
        working-directory: frontend
        run: |
          npm ci
          npm run check

  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      # Keep the minimum supported interpreter and the current stable one.
      # `requires-python` is `>=3.10` with no upper bound, so pip already
      # installs this package on 3.14 whether or not anything ever ran it
      # there — the same untested-claim gap the httpx floor job below exists
      # to close. 3.14 is a matrix entry rather than an assumption.
      # Windows below covers the platform-specific file-lock/path behavior.
      matrix:
        python-version: ["3.10", "3.12", "3.13", "3.14"]
        # "latest" = whatever pip resolves, which is what a fresh
        # `pip install cnequity` gets. See the floor job in `include`.
        httpx: ["latest"]
        include:
          # pyproject declares `httpx>=0.25` with no upper bound, so the jobs
          # above always test the newest release and the declared floor is
          # never exercised. httpx 0.28 changed `params` from merging into a
          # URL's existing query to replacing it outright — a silent, live
          # breakage (see adapters/eastmoney/em_auth.py) that only shows up
          # when the two ends of the declared range disagree. Pinning the floor
          # here makes the lower bound a tested claim rather than an assumption.
          - python-version: "3.12"
            httpx: "0.25.2"
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
          cache: pip

      - name: Install
        # No extras: every runtime source is a hard dependency now. The pip
        # upgrade is required — PEP 735 `--group` needs 25.1+.
        run: |
          python -m pip install --upgrade pip
          pip install -e . --group dev
          if [ "${{ matrix.httpx }}" != "latest" ]; then
            pip install "httpx==${{ matrix.httpx }}"
          fi

      - name: Report resolved httpx
        # The version is otherwise an invisible side effect of resolution drift;
        # print it so a failure names the httpx it happened on.
        run: python -c "import httpx; print('httpx', httpx.__version__)"

      - name: Test
        run: pytest --cov=cnequity --cov-report=term-missing --cov-report=xml

      - name: Test in random order
        # A test that passes only after another one left shared state behind
        # (a root logging handler, a registry entry) fails here, not months
        # later when an unrelated change reorders collection. The seed is in
        # the log, so `pytest -p randomly --randomly-seed=<seed>` reproduces it.
        if: matrix.python-version == '3.12' && matrix.httpx == 'latest'
        run: pytest tests/unit -q -p randomly

      - name: Upload coverage
        # Both 3.12 jobs would otherwise upload and double-count the same run.
        if: matrix.python-version == '3.12' && matrix.httpx == 'latest'
        uses: codecov/codecov-action@v5
        with:
          files: coverage.xml
          fail_ci_if_error: false
          token: ${{ secrets.CODECOV_TOKEN }}

  # Windows is a first-class runtime target (file locks, path forms, wheels).
  # One Python version is enough to catch platform regressions; Ubuntu covers
  # the minimum supported and current stable interpreters. Network tests stay
  # deselected via addopts.
  test-windows:
    runs-on: windows-latest
    env:
      # Force UTF-8 stdio so Chinese CLI/doctor strings never hit cp1252 EncodeError.
      PYTHONUTF8: "1"
      PYTHONIOENCODING: utf-8
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
          cache: pip

      - name: Install
        run: |
          python -m pip install --upgrade pip
          pip install -e . --group dev

      - uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: npm
          cache-dependency-path: frontend/package-lock.json

      - name: Check dashboard on Windows
        working-directory: frontend
        run: |
          npm ci
          npm run check

      - name: Test
        # tests/conftest.py handles Windows atexit noise only after a fully
        # successful session. Preserve pytest's exit code here so interruption
        # or an internal error cannot pass on a partial "N passed" summary.
        shell: bash
        run: pytest tests/unit -q

  # macOS is a supported runtime and also the platform used by the bundled
  # launchd runbook.  Keep one current interpreter here to exercise native
  # paths, advisory locks and package wheels without multiplying the matrix.
  test-macos:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: "3.14"
          cache: pip

      - name: Install
        run: |
          python -m pip install --upgrade pip
          pip install -e . --group dev

      - name: Test
        run: pytest tests/unit -q