chore: validate schema generation in CI

Adds schema generation and validation checks to the docs workflow.
CI currently only checks if Pydantic models can be generated from
existing spec files, but doesn't validate the schemas themselves or
check if spec/ stays in sync with source/.

This catches common mistakes like editing source schemas but forgetting
to run generate_schemas.py, or committing invalid JSON schemas.

Changes:
- Run generate_schemas.py in CI to verify generation works
- Run validate_specs.py to catch schema syntax errors
- Check git diff on spec/ to catch out-of-sync files
- Check for untracked files in spec/ to catch new generated files
- Add pre-commit hook for local validation
- Add source/**, generate_schemas.py, schema_utils.py, and
  validate_specs.py to workflow trigger paths

Author: sakinaroufid

.cspell/custom-words.txt

@@ -75,4 +75,5 @@ shopify
 superfences
 vulnz
 yaml
-ymlEDITMSG
+yml
+EDITMSG

.github/workflows/docs.yml

@@ -27,6 +27,7 @@ on:
       - "source/**"
       - "spec/**"
       - "generate_schemas.py"
+      - "schema_utils.py"
       - "validate_specs.py"
   pull_request:
     branches:
@@ -40,6 +41,7 @@ on:
       - "source/**"
       - "spec/**"
       - "generate_schemas.py"
+      - "schema_utils.py"
       - "validate_specs.py"
 
 jobs:
@@ -99,6 +101,11 @@ jobs:
             git diff --name-only spec/
             exit 1
           fi
+          if git ls-files --others --exclude-standard spec/ | grep -q .; then
+            echo "Warning: spec/ contains untracked generated files"
+            git ls-files --others --exclude-standard spec/
+            exit 1
+          fi
 
       - name: Install uv
         run: |

.pre-commit-hooks/check-schema-sync.sh

@@ -4,23 +4,50 @@
 
 set -e
 
-# Only check if source/ or generate_schemas.py changed
-if git diff --cached --name-only | grep -qE "(^source/|^generate_schemas\.py)"; then
+# Only check if schema inputs changed
+if git diff --cached --name-only | grep -qE "(^source/|^generate_schemas\.py|^schema_utils\.py)"; then
   echo "Source schemas changed, checking if spec/ needs regeneration..."
 
-  # Generate schemas
-  python generate_schemas.py > /dev/null 2>&1
+  # Prefer python3, but fall back to python for systems without a python3 shim
+  if command -v python3 &> /dev/null; then
+    PYTHON=python3
+  elif command -v python &> /dev/null; then
+    PYTHON=python
+  else
+    echo "Error: python3 or python not found. Please install Python."
+    exit 1
+  fi
+
+  # Generate schemas and keep output for debugging
+  if ! "$PYTHON" generate_schemas.py; then
+    echo ""
+    echo "Error: Failed to generate schemas. Please fix errors above."
+    exit 1
+  fi
+
+  # Check for differences (including untracked files)
+  if git ls-files --others --exclude-standard spec/ | grep -q .; then
+    echo ""
+    echo "Error: spec/ contains untracked generated files"
+    echo ""
+    echo "Files that need adding:"
+    git ls-files --others --exclude-standard spec/
+    echo ""
+    echo "Run: $PYTHON generate_schemas.py"
+    echo "Then stage and commit the updated spec/ files"
+    exit 1
+  fi
 
-  # Check for differences
+  # Check for differences in tracked files
   if ! git diff --exit-code spec/ > /dev/null 2>&1; then
     echo ""
     echo "Error: spec/ is out of sync with source/"
     echo ""
     echo "Files that need updating:"
     git diff --name-only spec/
     echo ""
-    echo "Run: python generate_schemas.py"
-    echo "Then commit the updated spec/ files"
+    echo "Run: $PYTHON generate_schemas.py"
+    echo "Then stage and commit the updated spec/ files"
     exit 1
   fi
 fi