ci.yml

name: test-and-build

on:
  pull_request:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  unit-lint:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        python-version: ["3.11", "3.12"]

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          python -m pip install -e .[dev]
      - name: Run unit tests
        run: pytest -q

  paper-gallery-artifacts:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          python -m pip install -e .[dev]
      - name: Regenerate paper gallery artifacts
        run: python tools/paper_examples/build_gallery.py
      - name: Fail on paper gallery drift
        run: |
          git diff --exit-code -- \
            docs/paper_examples.md \
            docs/figures/manifest.json \
            docs/figures/example01/README.md \
            docs/figures/example02/README.md \
            docs/figures/example03/README.md \
            docs/figures/example04/README.md \
            docs/figures/example05/README.md

  parity-report-artifacts:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          python -m pip install -e .[dev]
      - name: Regenerate parity report
        run: python tools/parity/build_report.py
      - name: Fail on parity report drift
        run: git diff --exit-code -- parity/report.md

  docs-build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          python -m pip install -e .[dev]
      - name: Regenerate paper gallery artifacts
        run: python tools/paper_examples/build_gallery.py
      - name: Build docs
        run: python -m sphinx -W -b html docs docs/_build/html

  installer-smoke:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          python -m pip install -e .[dev]
      - name: Smoke test module installer without data download
        run: python -m nstat.install --download-example-data never --no-rebuild-doc-search
      - name: Smoke test compatibility no-op flag
        run: python -m nstat.install --download-example-data never --no-rebuild-doc-search --clean-user-path-prefs

  data-integrity:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          python -m pip install -e .[dev]
      - name: Run dataset integrity tests
        run: pytest -q tests/test_datasets.py

  notebook-smoke:
    runs-on: ubuntu-latest
    env:
      NSTAT_DATA_DIR: ${{ github.workspace }}/.nstat_data_cache

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - name: Cache example data
        uses: actions/cache@v4
        with:
          path: ${{ env.NSTAT_DATA_DIR }}
          key: nstat-example-data-v1
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          python -m pip install -e .[dev]
          python -m pip install ipykernel
          python -m ipykernel install --user --name python3 --display-name "Python 3"
      - name: Execute Python notebook smoke group
        run: python tools/notebooks/run_notebooks.py --group ci_smoke --timeout 600

  notebook-parity-core:
    runs-on: ubuntu-latest
    env:
      NSTAT_DATA_DIR: ${{ github.workspace }}/.nstat_data_cache

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - name: Cache example data
        uses: actions/cache@v4
        with:
          path: ${{ env.NSTAT_DATA_DIR }}
          key: nstat-example-data-v1
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          python -m pip install -e .[dev]
          python -m pip install ipykernel
          python -m ipykernel install --user --name python3 --display-name "Python 3"
      - name: Execute Python notebook parity-core group
        run: python tools/notebooks/run_notebooks.py --group parity_core --timeout 900

  notebook-changed-pr:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    env:
      NSTAT_DATA_DIR: ${{ github.workspace }}/.nstat_data_cache

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - name: Cache example data
        uses: actions/cache@v4
        with:
          path: ${{ env.NSTAT_DATA_DIR }}
          key: nstat-example-data-v1
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          python -m pip install -e .[dev]
          python -m pip install ipykernel
          python -m ipykernel install --user --name python3 --display-name "Python 3"
      - name: Resolve changed notebook topics
        id: changed_topics
        run: |
          TOPICS=$(python tools/notebooks/changed_topics.py \
            --base-sha "${{ github.event.pull_request.base.sha }}" \
            --head-sha "${{ github.sha }}")
          echo "topics=${TOPICS}" >> "$GITHUB_OUTPUT"
          echo "Resolved notebook topics: ${TOPICS:-<none>}"
      - name: Execute changed notebook topics
        if: steps.changed_topics.outputs.topics != ''
        run: python tools/notebooks/run_notebooks.py --group full --topics "${{ steps.changed_topics.outputs.topics }}" --timeout 1200
      - name: No notebook changes detected
        if: steps.changed_topics.outputs.topics == ''
        run: echo "No changed notebook topics to execute."

  cleanroom-compliance:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          python -m pip install -e .[dev]
      - name: Run API surface checks
        run: pytest -q tests/test_api_surface.py tests/test_cleanroom_boundary.py

  symbol-surface-audit:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          python -m pip install -e .[dev]
      - name: Verify audited MATLAB-facing runtime surface
        run: pytest -q tests/test_matlab_symbol_surface.py tests/test_class_fidelity_audit.py tests/test_parity_report.py

  regenerate-figures:
    runs-on: ubuntu-latest
    env:
      NSTAT_DATA_DIR: ${{ github.workspace }}/.nstat_data_cache

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - name: Cache example data
        uses: actions/cache@v4
        with:
          path: ${{ env.NSTAT_DATA_DIR }}
          key: nstat-example-data-v1
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          python -m pip install -e .[dev]
      - name: Regenerate all paper figures
        run: python examples/paper/regenerate_all_figures.py
      - name: Upload regenerated figures
        uses: actions/upload-artifact@v4
        with:
          name: paper-figures
          path: docs/figures/
          retention-days: 30