Add pipeline to quickly validate Jupyter notebooks

Author: JohT

.github/workflows/internal-check-notebooks.yml

@@ -0,0 +1,93 @@
+name: Check Jupyter Notebooks
+
+on:
+  pull_request:
+    branches:
+      - main
+    # Run when notebooks, Python dependencies, or this workflow change
+    paths:
+      - 'domains/**/explore/*.ipynb'
+      - 'pyproject.toml'
+      - 'uv.lock'
+      - 'scripts/activateUvEnvironment.sh'
+      - '.github/workflows/internal-check-notebooks.yml'
+
+jobs:
+  smoke-test:
+    runs-on: ubuntu-22.04
+
+    steps:
+    - name: Checkout GIT Repository
+      uses: actions/checkout@v6
+
+    - name: (uv Setup) Install uv
+      uses: astral-sh/setup-uv@v6
+      with:
+        python-version: '3.12'
+
+    - name: (uv Setup) Sync dependencies from lockfile
+      run: uv sync --frozen
+
+    - name: Execute and check all notebooks
+      # NEO4J_INITIAL_PASSWORD is required by notebooks but Neo4j is not available in CI.
+      # --allow-errors lets all cells run even if Neo4j connection or query cells fail.
+      # Only ModuleNotFoundError, ImportError, and SyntaxError are treated as fatal —
+      # all Neo4j connection errors and cascading errors from missing data are ignored.
+      env:
+        NEO4J_INITIAL_PASSWORD: smoke-test-no-neo4j
+      run: |
+        uv run --with nbconvert python3 - <<'PYEOF'
+        import json, subprocess, sys
+        from pathlib import Path
+
+        fatal_error_types = {"ModuleNotFoundError", "ImportError", "SyntaxError"}
+        notebooks = sorted(Path("domains").glob("**/explore/*.ipynb"))
+        failures = []
+
+        for notebook in notebooks:
+            print(f"\n--- {notebook} ---", flush=True)
+            executed = Path("executed.ipynb")
+
+            result = subprocess.run(
+                [
+                    sys.executable, "-m", "nbconvert",
+                    "--to", "notebook",
+                    "--execute",
+                    "--allow-errors",
+                    "--ExecutePreprocessor.timeout=300",
+                    "--output", "executed",
+                    "--output-dir", ".",
+                    str(notebook),
+                ],
+                capture_output=True,
+                text=True,
+            )
+            print(result.stdout, end="")
+            print(result.stderr, end="", file=sys.stderr)
+
+            if result.returncode != 0:
+                failures.append(f"{notebook}: nbconvert exited with code {result.returncode}")
+                continue
+
+            nb = json.loads(executed.read_text())
+            for cell_idx, cell in enumerate(nb["cells"], 1):
+                for output in cell.get("outputs", []):
+                    if output.get("output_type") != "error":
+                        continue
+                    ename = output.get("ename", "")
+                    evalue = output.get("evalue", "")
+                    if ename in fatal_error_types:
+                        failures.append(f"{notebook} cell {cell_idx}: {ename}: {evalue}")
+
+            cells_total = len(nb["cells"])
+            print(f"OK: {cells_total} cells executed.")
+
+        print(f"\n{'='*60}")
+        if failures:
+            print(f"FAILED ({len(failures)} error(s)):", file=sys.stderr)
+            for f in failures:
+                print(f"  {f}", file=sys.stderr)
+            sys.exit(1)
+
+        print(f"All {len(notebooks)} notebooks passed.")
+        PYEOF