feat(overflow): interactive overflow analysis tab

.circleci/config.yml

@@ -10,6 +10,9 @@ jobs:
       - image: cimg/python:3.10
     steps:
       - checkout
+      - run:
+          name: Install Graphviz (provides ``dot``)
+          command: sudo apt-get update && sudo apt-get install -y graphviz
       - run:
           name: Install Dependencies
           command: |

.github/workflows/parity.yml

@@ -39,6 +39,21 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: '3.11'
+      # The parity check needs an up-to-date standalone bundle to
+      # diff against. `frontend/dist-standalone/` is gitignored, so
+      # in CI we have to (re)build it from source — otherwise the
+      # script falls back to the frozen `standalone_interface_legacy.html`
+      # which lags behind the React source by design.
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: frontend/package-lock.json
+      - name: Build standalone bundle
+        working-directory: frontend
+        run: |
+          npm ci
+          npm run build:standalone
       - name: Run parity check
         run: python scripts/check_standalone_parity.py
       - name: Emit Markdown summary
@@ -58,6 +73,16 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: '3.11'
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: frontend/package-lock.json
+      - name: Build standalone bundle
+        working-directory: frontend
+        run: |
+          npm ci
+          npm run build:standalone
       - name: Run session-fidelity check
         run: python scripts/check_session_fidelity.py
 
@@ -73,6 +98,16 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: '3.11'
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: frontend/package-lock.json
+      - name: Build standalone bundle
+        working-directory: frontend
+        run: |
+          npm ci
+          npm run build:standalone
       - name: Run gesture-sequence check
         run: python scripts/check_gesture_sequence.py
 
@@ -90,6 +125,16 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: '3.11'
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: frontend/package-lock.json
+      - name: Build standalone bundle
+        working-directory: frontend
+        run: |
+          npm ci
+          npm run build:standalone
       - name: Run invariants check
         run: python scripts/check_invariants.py
 

.github/workflows/test.yml

@@ -7,21 +7,29 @@ on:
     branches: [ main ]
 
 jobs:
+  # ------------------------------------------------------------------
+  # Fast lane: every backend test that does NOT need the graphviz
+  # `dot` binary. Skips the system-package install entirely (which
+  # used to hang for ~8 minutes on the Azure apt mirror) and runs the
+  # ~720 pytest items in ~15 seconds.
+  # ------------------------------------------------------------------
   test-backend:
+    name: Backend tests (no graphviz)
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - name: Set up Python 3.10
         uses: actions/setup-python@v5
         with:
           python-version: "3.10"
+          cache: 'pip'
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
           pip install ".[test]"
           pip install --no-deps expert_op4grid_recommender
-      - name: Run Pytest
-        run: pytest
+      - name: Run Pytest (excluding graphviz-dependent tests)
+        run: pytest --ignore=expert_backend/tests/test_overflow_html_dim_logic.py
 
   test-frontend:
     runs-on: ubuntu-latest
@@ -45,3 +53,39 @@ jobs:
         run: |
           cd frontend
           npm run lint
+
+  # ------------------------------------------------------------------
+  # Slow lane: the small subset of backend tests that exercise the
+  # upstream interactive-HTML viewer through pydot → graphviz `dot`.
+  # Gated behind the fast lanes so a regression in non-graphviz code
+  # is reported in ~1 minute, and only the prod/load-layer fixtures
+  # pay the (cached) apt install cost.
+  #
+  # `awalsh128/cache-apt-pkgs-action` caches the resolved .deb files
+  # across runs — first run is ~30 s, subsequent runs restore from
+  # cache in ~5 s, vs. the ~8 minutes the bare `apt-get update` was
+  # taking on the Azure mirror.
+  # ------------------------------------------------------------------
+  test-backend-graphviz:
+    name: Backend tests requiring graphviz
+    needs: [test-backend, test-frontend]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+          cache: 'pip'
+      - name: Install Graphviz (cached apt)
+        uses: awalsh128/cache-apt-pkgs-action@v1
+        with:
+          packages: graphviz
+          version: 1.0
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install ".[test]"
+          pip install --no-deps expert_op4grid_recommender
+      - name: Run graphviz-dependent Pytest subset
+        run: pytest expert_backend/tests/test_overflow_html_dim_logic.py

CONTRIBUTING.md

@@ -15,6 +15,36 @@ pip install --no-deps expert_op4grid_recommender
 uvicorn expert_backend.main:app --host 0.0.0.0 --port 8000
 ```
 
+#### System prerequisite — Graphviz (`dot`)
+
+The overflow-graph rendering pipeline shells out to Graphviz's
+`dot` binary. `pip install` attempts a best-effort auto-install via
+the platform's package manager (apt / dnf / pacman / apk on Linux,
+Homebrew or MacPorts on macOS, Chocolatey / winget / Scoop on
+Windows); set `COSTUDY4GRID_SKIP_GRAPHVIZ_INSTALL=1` to opt out.
+Modern wheel-based installs may skip the `setup.py` post-install
+hook — re-run it manually with the bundled console script if
+`dot -V` fails:
+
+```bash
+costudy4grid-install-graphviz
+```
+
+If the auto-install can't elevate (no `sudo`, locked package DB,
+unsupported package manager), install Graphviz by hand:
+
+| Platform                | Command                                           |
+|-------------------------|---------------------------------------------------|
+| Debian / Ubuntu         | `sudo apt-get install graphviz`                   |
+| RHEL / Fedora           | `sudo dnf install graphviz` (or `yum`)            |
+| Arch                    | `sudo pacman -S graphviz`                         |
+| Alpine                  | `sudo apk add graphviz`                           |
+| macOS (Homebrew)        | `brew install graphviz`                           |
+| macOS (MacPorts)        | `sudo port install graphviz`                      |
+| Windows (Chocolatey)    | `choco install graphviz`                          |
+| Windows (winget)        | `winget install Graphviz.Graphviz`                |
+| Windows (Scoop)         | `scoop install graphviz`                          |
+
 ### Frontend
 
 ```bash