Add example execution validation to quality checks and CI/CD

- Create check-examples.py script to validate all example files execute successfully
- Add example execution check to run-quality-checks.sh script
- Add example execution step to CI/CD pipeline
- Fix API usage in example files:
  - Fix import in basic_assessment.py to use dispatcher.query_dispatcher
  - Fix bibtex_processing.py to use correct result attributes
- All examples now execute successfully and are validated in CI/CD

This ensures the Python API examples provided for JOSS remain functional
and serve as reliable documentation for users.

[AI-assisted]

Author: florath

.github/workflows/ci.yml

@@ -55,6 +55,10 @@ jobs:
       run: |
         python scripts/check-logging.py
 
+    - name: Check example execution
+      run: |
+        python scripts/check-examples.py
+
   test:
     name: Tests
     runs-on: ubuntu-latest

scripts/check-examples.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: MIT
+"""Check that all example scripts execute successfully."""
+
+import subprocess
+import sys
+from pathlib import Path
+
+
+def main() -> int:
+    """Execute all example scripts and verify they run without errors."""
+    # Find the project root (parent of scripts directory)
+    script_dir = Path(__file__).parent
+    project_root = script_dir.parent
+    examples_dir = project_root / "examples"
+
+    # Find all Python example files
+    example_files = sorted(examples_dir.glob("*.py"))
+
+    if not example_files:
+        print("No example files found in examples/ directory")
+        return 1
+
+    print(f"Checking {len(example_files)} example script(s)...\n")
+
+    failed_examples = []
+
+    for example_file in example_files:
+        print(f"Running: {example_file.name}")
+        try:
+            # Run the example with a timeout
+            result = subprocess.run(
+                [sys.executable, str(example_file)],
+                cwd=project_root,
+                capture_output=True,
+                text=True,
+                timeout=30,
+            )
+
+            if result.returncode != 0:
+                failed_examples.append(example_file.name)
+                print(f"❌ FAILED: {example_file.name}")
+                print(f"\nStdout:\n{result.stdout}")
+                print(f"\nStderr:\n{result.stderr}")
+                print()
+            else:
+                print(f"✅ PASSED: {example_file.name}\n")
+
+        except subprocess.TimeoutExpired:
+            failed_examples.append(example_file.name)
+            print(f"❌ TIMEOUT: {example_file.name} (exceeded 30 seconds)\n")
+        except Exception as e:
+            failed_examples.append(example_file.name)
+            print(f"❌ ERROR: {example_file.name}: {e}\n")
+
+    # Print summary
+    print("=" * 60)
+    if failed_examples:
+        print(f"❌ Example Check FAILED: {len(failed_examples)} script(s) failed:")
+        for example in failed_examples:
+            print(f"  - {example}")
+        return 1
+    else:
+        print(f"✅ All {len(example_files)} example script(s) executed successfully")
+        return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/run-quality-checks.sh

@@ -55,6 +55,9 @@ run_check "Logging consistency" python scripts/check-logging.py || true
 # 6. SPDX license identifier check
 run_check "SPDX license identifiers" python scripts/check-spdx.py || true
 
+# 7. Example execution check
+run_check "Example execution" python scripts/check-examples.py || true
+
 # Final summary
 echo -e "${BLUE}========================================${NC}"
 if [ $FAILED -eq 0 ]; then