Add pipeline to quickly validate Jupyter notebooks

Author: JohT

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

@@ -0,0 +1,98 @@
+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:
+  discover-notebooks:
+    runs-on: ubuntu-22.04
+    outputs:
+      notebooks: ${{ steps.list.outputs.notebooks }}
+
+    steps:
+    - name: Checkout GIT Repository
+      uses: actions/checkout@v6
+
+    - name: List all explore notebooks
+      id: list
+      run: |
+        notebooks=$(find domains -path '*/explore/*.ipynb' | sort | python3 -c "
+        import json, sys
+        paths = [p.strip() for p in sys.stdin if p.strip()]
+        print(json.dumps(paths))
+        ")
+        echo "notebooks=$notebooks" >> "$GITHUB_OUTPUT"
+
+  smoke-test-notebook:
+    needs: discover-notebooks
+    runs-on: ubuntu-22.04
+    strategy:
+      fail-fast: false
+      matrix:
+        notebook: ${{ fromJson(needs.discover-notebooks.outputs.notebooks) }}
+
+    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 notebook (allow cell errors)
+      # 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.
+      env:
+        NEO4J_INITIAL_PASSWORD: smoke-test-no-neo4j
+      run: |
+        uv run --with nbconvert python -m nbconvert \
+          --to notebook \
+          --execute \
+          --allow-errors \
+          --ExecutePreprocessor.timeout=300 \
+          --output executed \
+          --output-dir . \
+          "${{ matrix.notebook }}"
+
+    - name: Check for import and syntax errors in executed notebook
+      # Only fatal errors that prevent the notebook from running at all are checked:
+      # ModuleNotFoundError, ImportError, SyntaxError.
+      # All Neo4j connection errors and cascading errors from missing data are expected and ignored.
+      run: |
+        uv run python3 - <<'PYEOF'
+        import json, sys
+
+        nb = json.load(open("executed.ipynb"))
+        fatal_error_types = {"ModuleNotFoundError", "ImportError", "SyntaxError"}
+
+        failures = []
+        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"Cell {cell_idx}: {ename}: {evalue}")
+
+        if failures:
+            print("Fatal errors found in notebook:", file=sys.stderr)
+            for f in failures:
+                print(f"  {f}", file=sys.stderr)
+            sys.exit(1)
+
+        print(f"OK: {len(nb['cells'])} cells executed, no import/syntax errors.")
+        PYEOF