feat: move validate notebooks action (#15)

Move notebook validation script to `ci-actions`

Looking for advice on whether to include a workflow yaml, and what it should look like



Approved-by: ktdreyer

Approved-by: courtneypacheco

Author: mergify[bot]

README.md

@@ -19,6 +19,7 @@ Below is a list of the in-house GitHub actions stored in this repository:
 | [detect-exposed-workflow-secrets](./actions/detect-exposed-workflow-secrets/detect-exposed-workflow-secrets.md) | Used to detect when a contributor's PR would expose a GitHub secret through one or more workflow files that auto-trigger on PRs, and aborts that contributor's PR build before it can start. | <ul><li>Prevent accidental secrets exposure through GitHub workflow files that auto-trigger on PR builds.</li></ul> |
 | [free-disk-space](./actions/free-disk-space/free-disk-space.md) | Used to reclaim disk space on either a GitHub or EC2 runner. | <ul><li>If a CI job tends to fail due to "insufficient disk space"</li><li>If you want to reduce cloud costs by reclaiming disk space instead of increasing your writeable cloud storage to compensate for a bloated EC2 image</li></ul> |
 | [launch-ec2-runner-with-fallback](./actions/launch-ec2-runner-with-fallback/launch-ec2-runner-with-fallback.md) | Used launch an EC2 instance in AWS, either as a spot instance or a dedicated instance. If your preferred availability zone lacks availability for your instance type, "backup" availability zones will be tried. | <ul><li>Insufficient capacity in AWS (i.e., AWS lacks availablility for your desired EC2 instance type in your preferred availability zone)</li><li>Cost savings (i.e., You want to try launching your EC2 runner as a spot instance first)</li></ul> |
+| [validate-notebooks](./actions/launch-ec2-runner-with-fallback/launch-ec2-runner-with-fallback.md) | Used to validate `.ipynb` files | <ul><li>I maintain a collection of `.ipynb` files and run ci jobs to test them. I  would like to quickly verify that the files are formatted correctly before spinning up more complex or expensive CI jobs to test those notebooks.</li></ul>
 
 ## ❓ How to Use One or More In-House GitHub Actions
 

actions/validate-notebooks/action.yml

@@ -0,0 +1,19 @@
+name: 'Validate Notebooks'
+description: 'Validates Jupyter Notebook Files'
+author: "InstructLab"
+
+inputs:
+  path:
+    description: a path to a file or directory containing jupyter notebook files; accepts multiple arguments
+    required: true
+    type: string
+
+runs:
+  using: "composite"
+  steps:
+    - name: Install Dependencies
+      shell: bash
+      run: pip install nbformat
+    - name: Validate Notebooks
+      shell: bash
+      run: python ${{ github.action_path }}/validate.py $notebook_paths ${{ inputs.path }}

actions/validate-notebooks/validate-notebooks.md

@@ -0,0 +1,32 @@
+# Validate Notebooks
+
+## Overview
+
+Validate Notebooks is a simple action that reads a file with the `.ipynb` extension, and verifies that body of that file is a valid jupyter notebook.
+
+## When to Use it?
+
+This tool is best used as a preliminary step for any CI workflows involving jupyter notebooks. This script is best used as a first test for any workflows testing
+jupyter notebooks. If any of the notebooks passed to it are not valid, it will fail at the end of the job, and report out all of the errors it encountered. This will prevent jobs that may be more complicated from getting started, then failing unexpectedly.
+
+## Usage
+
+This is a reusable workflow, and can be referenced and used in any github actions workflow. Here is an example of how to import this into a workflow that needs to test a notebook file named `my_notebook.ipynb` and all the notebooks contained in the directory `./directory_containing_notebooks/`:
+
+```yaml
+jobs:
+  example-job:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout "validate-notebooks" in-house CI action
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          repository: instructlab/ci-actions
+          path: ci-actions
+          sparse-checkout: |
+            actions/validate-notebooks
+      - name: Validate Jupyter Notebooks
+        uses: ./ci-actions/actions/validate-notebooks
+        with:
+          notebook_paths: "notebooks/"
+```

actions/validate-notebooks/validate.py

@@ -0,0 +1,83 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+This script validates a Jupyter notebook file.
+Usage: python validate_notebook.py <notebook.ipynb>
+"""
+
+# Standard
+from pathlib import Path
+import argparse
+import os
+import sys
+
+# Third Party
+import nbformat  # type: ignore[import-not-found]
+
+
+def validate_notebook(file_path) -> bool:
+    try:
+        with open(file_path, "r", encoding="utf-8") as f:
+            nb = nbformat.read(f, as_version=4)
+        nbformat.validate(nb)
+        print(f"{file_path} is a valid Jupyter notebook.")
+        return True
+    except nbformat.ValidationError as e:
+        print(f"{file_path} is not a valid Jupyter notebook. Validation error: {e}")
+        return False
+
+
+def list_valid_files(paths: list) -> list:
+    """
+    list valid files finds and returns a list of .ipynb files in the given list of paths
+    """
+
+    all_files = []
+    for path in paths:
+        if not os.path.exists(path):
+            print(f"invalid path {path}: path does not exist")
+            continue
+        if os.path.isfile(path):
+            if ".ipynb" not in path:
+                print(
+                    f"invalid path {path}: files must be ipython notebooks"
+                )  # fatal error: files must be .ipynb
+                sys.exit(1)
+            all_files.append(path)
+        elif os.path.isdir(path):
+            search_dir = Path(path)
+            discovered_notebook_files = search_dir.rglob("*.ipynb")
+            for file in discovered_notebook_files:
+                all_files.append(file)
+    return all_files
+
+
+if __name__ == "__main__":
+    invalid_notebook_found = False
+    parser = argparse.ArgumentParser(
+        description="validates jupyter notebook files by checking the underlying JSON. This will not run the notebooks."
+    )
+    parser.add_argument(
+        "path",
+        metavar="path",
+        type=str,
+        nargs="+",
+        help="a path to an .ipynb file, or a directory containing .ipynb files",
+    )
+    args = parser.parse_args()
+    if len(args.path) < 1:
+        print("must provide at least one path")
+        sys.exit(1)
+
+    user_provided_paths = list_valid_files(args.path)
+    if len(user_provided_paths) < 1:
+        print("no valid file paths to jupyter notebooks provided")
+        sys.exit(1)
+
+    for user_path in user_provided_paths:
+        ok = validate_notebook(user_path)
+        if not ok:
+            invalid_notebook_found = True
+
+    if invalid_notebook_found:
+        sys.exit(1)  # indicate to ci environment that something failed