Add metadata previewImages validation (#887)

.github/workflows/build-branch.yml

@@ -54,17 +54,25 @@ on:
         type: boolean
         default: false
 
+      # TODO: This is temp workaround to add metadata previewImages validation to this job. Once the static asset files
+      #       are centralized properly, then this parameter can be removed.
+      validate_metadata_preview_images:
+        description: Validate the metadata previewImages after sphinx-build concludes
+        required: false
+        type: boolean
+        default: false
+
 jobs:
   validate-inputs:
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-latest
     steps:
       - name: Validate inputs.sphinx_build_output_format
         run: |
           valid_choices='html json'
           [[ " $valid_choices " =~ " ${{ inputs.sphinx_build_output_format }} " ]] && exit 0 || exit 1
 
   compute-build-strategy-matrix:
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/checkout@v3
@@ -78,9 +86,7 @@ jobs:
           python-version: 3.9
 
       - name: Install QML Pipeline Utils
-        run: |
-          cd .github/workflows/qml_pipeline_utils
-          pip install .
+        run: pip install .github/workflows/qml_pipeline_utils
 
       - name: Execution Times Cache
         id: execution_times_cache
@@ -217,7 +223,7 @@ jobs:
       worker-load-artifact-name: ${{ steps.compute-strategy-matrix.outputs.worker_load_artifact_name }}
 
   validate-poetry-lock-file:
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-latest
 
     steps:
       - uses: actions/checkout@v3
@@ -244,7 +250,7 @@ jobs:
         run: ${{ steps.poetry.outputs.bin }} lock --check
 
   build-branch:
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-latest
     needs:
       - compute-build-strategy-matrix
       - validate-inputs
@@ -279,9 +285,7 @@ jobs:
           echo "${{ github.workspace }}/venv/bin" >> $GITHUB_PATH
 
       - name: Install QML Pipeline Utils
-        run: |
-          cd .github/workflows/qml_pipeline_utils
-          ${{ steps.venv.outputs.location }}/bin/python3 -m pip install .
+        run: ${{ steps.venv.outputs.location }}/bin/python3 -m pip install .github/workflows/qml_pipeline_utils
 
       - name: Install Poetry
         id: poetry
@@ -427,6 +431,25 @@ jobs:
           
           cat /tmp/execution_times/execution_times.json | jq
 
+      # TODO: This is a temporary step to include metadata validation as a part of the build step.
+      #       One the assets in QML are centralized with proper naming convention, this step can be removed
+      #       and the validation can be done with `validate-demo-metadata.yml` workflow.
+      - name: Validate metadata previewImages
+        run: |
+          metadata_files=()
+          input_demos_to_build=$(jq -r '[.[].name]|join(" ")' ${{ steps.worker_tasks.outputs.file_name }})
+          
+          for metadata_file in $input_demos_to_build
+          do
+            metadata_files+=("demonstrations/${metadata_file%.py}.metadata.json")
+          done
+          
+          metadata_files_str="${metadata_files[@]}"
+          
+          qml_pipeline_utils validate-metadata-preview-images \
+          --metadata-files $metadata_files_str \
+          --build-dir="${{ github.workspace }}/_build/html"
+
       - name: Upload Execution Times
         uses: actions/upload-artifact@v3
         with:
@@ -490,7 +513,7 @@ jobs:
             !_build/html/glossary
 
   aggregate_build:
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-latest
     if: inputs.skip_execution_times_aggregation == false || inputs.skip_sphinx_build_file_aggregation == false
     needs:
       - build-branch

.github/workflows/build-pr.yml

@@ -65,6 +65,30 @@ jobs:
           done
           echo "files=${demo_filenames[@]}" >> $GITHUB_OUTPUT
 
+      - name: Detect Metadata Files that need to be changed
+        id: metadata_files_to_check
+        env:
+          DEMOS_TO_BUILD: ${{ steps.formatted_changed_demos.outputs.files }}
+        run: |
+          metadata_files=()
+          input_demos_to_build="$DEMOS_TO_BUILD"
+          
+          if [ -z "$input_demos_to_build" ]; then
+            readarray -d '' metadata_files < <(find demonstrations -name "*.metadata.json" -not -path "demonstrations/demonstrations_categories.metadata.json" -print0)
+          else
+            for metadata_file in $input_demos_to_build
+            do
+              metadata_files+=("demonstrations/${metadata_file%.py}.metadata.json")
+            done
+          fi
+          
+          metadata_files_str="${metadata_files[@]}"
+          
+          echo 'The following metadata files will be validated =>'
+          echo "$metadata_files_str"
+          
+          echo "file_names=$metadata_files_str" >> $GITHUB_OUTPUT
+
       - name: Set number of workers needed
         id: num_workers
         env:
@@ -81,12 +105,25 @@ jobs:
       num_workers: ${{ steps.num_workers.outputs.num_workers }}
       build_all_demos: ${{ steps.build_all_demos.outputs.build_all_demos }}
       demos_to_build: ${{ steps.formatted_changed_demos.outputs.files }}
+      metadata_file_names: ${{ steps.metadata_files_to_check.outputs.file_names }}
+
+  validate_metadata:
+    uses: ./.github/workflows/validate-demo-metadata.yml
+
+    needs:
+      - set_build_params
+
+    with:
+      branch: ${{ github.ref }}
+      metadata_files: ${{ needs.set_build_params.outputs.metadata_file_names }}
+      skip_metadata_preview_image_value_validation: true  # TODO: This can be reverted once the static assets are centralized
 
   build:
     uses: ./.github/workflows/build-branch.yml
 
     needs:
       - set_build_params
+      - validate_metadata
 
     # Only run if we need to build all the demos or a subset of demos.
     # If build_all_demos is false AND demos_to_build_is blank, this means
@@ -111,12 +148,12 @@ jobs:
       sphinx_build_output_format: html
       sphinx_examples_to_build: ${{ needs.set_build_params.outputs.demos_to_build }}
 
-
   save-build-context:
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-latest
 
     needs:
       - build
+      - validate_metadata
 
     steps:
       - name: Save Pull Request Event Context

.github/workflows/deploy-pr.yml

@@ -8,7 +8,7 @@ on:
 
 jobs:
   deploy:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-latest
     if: github.event.workflow_run.conclusion == 'success'
     steps:
       - name: Set Build Context File Prefix

.github/workflows/qml_pipeline_utils/pyproject.toml

@@ -0,0 +1,14 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "qml_pipeline_utils"
+version = "1"
+requires-python = ">= 3.9"
+dependencies = [
+    'tqdm~=4.66.0'
+]
+
+[project.scripts]
+qml_pipeline_utils = "qml_pipeline_utils.cli:cli_parser"

.github/workflows/qml_pipeline_utils/qml_pipeline_utils/cli.py

@@ -1,5 +1,6 @@
 import json
 import argparse
+import os
 from pathlib import Path
 
 import qml_pipeline_utils.services
@@ -153,6 +154,20 @@ def cli_parser():
         "glob-pattern",
     )
 
+    subparsers_validate_metadata_preview_images = subparsers.add_parser(
+        "validate-metadata-preview-images",
+        description="Validate the metadata"
+    )
+    add_flags_to_subparser(
+        subparsers_validate_metadata_preview_images,
+        "build-dir"
+    )
+    subparsers_validate_metadata_preview_images.add_argument(
+        "--metadata-files",
+        help="List of paths to metadata files",
+        nargs="+"
+    )
+
     parser_results = parser.parse_args()
 
     cli_actions = {
@@ -225,6 +240,13 @@ def cli_parser():
                 "sphinx_build_type": getattr(parser_results, "build_type", ""),
             },
         },
+        "validate-metadata-preview-images": {
+            "func": qml_pipeline_utils.services.validate_metadata_preview_images,
+            "kwargs": {
+                "metadata_files": getattr(parser_results, "metadata_files", []),
+                "sphinx_build_directory": Path(getattr(parser_results, "build_dir", ""))
+            }
+        }
     }
 
     if parser_results.action not in cli_actions:

.github/workflows/qml_pipeline_utils/qml_pipeline_utils/services/__init__.py

@@ -6,3 +6,4 @@
 from .clean_sitemap import clean_sitemap
 from .show_worker_files import show_worker_files
 from .parse_execution_times import parse_execution_times
+from .validate_metadata_preview_images import validate_metadata_preview_images

.github/workflows/qml_pipeline_utils/qml_pipeline_utils/services/validate_metadata_preview_images.py

@@ -0,0 +1,41 @@
+import os
+import json
+from pathlib import Path
+from typing import List
+
+from tqdm import tqdm
+
+
+def validate_metadata_preview_images(metadata_files: List[str], sphinx_build_directory: Path):
+    working_dir = Path(os.getcwd())
+
+    if sphinx_build_directory.is_absolute():
+        sphinx_build_directory = sphinx_build_directory
+    else:
+        sphinx_build_directory = working_dir / sphinx_build_directory
+
+    for metadata_file in metadata_files:
+        if not metadata_file.startswith("/"):
+            metadata_file_path = Path(working_dir) / metadata_file
+        else:
+            metadata_file_path = Path(metadata_file)
+
+        with metadata_file_path.open() as fh:
+            metadata = json.load(fh)
+
+        preview_images = metadata.get("previewImages", [])
+
+        image_uris = [
+            image["uri"]
+            for image in preview_images
+        ]
+
+        for image_uri in tqdm(image_uris, ascii=True, desc=metadata_file):
+            if not image_uri.startswith("/"):
+                print(f"  Metadata file {metadata_file} contains either remote image uri or non-absolute path "
+                      f"for previewImage {image_uri}. Remote image paths cannot be validated at this time. Skipping.")
+                continue
+
+            uri_path = sphinx_build_directory / image_uri[1:]
+
+            assert uri_path.exists(), f"Could not find previewImage {image_uri}"

.github/workflows/teardown-pr.yml

@@ -11,7 +11,7 @@ env:
 
 jobs:
   teardown:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-latest
     steps:
       - name: Check if deployment exists
         id: check_deployment