ci: check config schema is up to date

Author: alandefreitas

.github/workflows/ci.yml

@@ -386,7 +386,13 @@ jobs:
           package-artifact: false
 
       - name: Check YAML schema
-        run: npx -y -p ajv-cli -- ajv compile -s docs/mrdocs.schema.json
+        run: |
+          # Find python
+          python=$(command -v python3 || command -v python)
+          # The schema in this branch is up to date 
+          "$python" ./util/generate-yaml-schema.py --check
+          # The schema in the docs folder is valid
+          npx -y -p ajv-cli -- ajv compile -s docs/mrdocs.schema.json
 
       - name: Upload GitHub Release Artifacts
         if: ${{ matrix.is-main && matrix.compiler != 'clang' }}

util/generate-yaml-schema.py

@@ -1,6 +1,7 @@
 import json
 import sys
 import os
+import argparse
 
 # NotRequired was added in 3.11
 if sys.version_info < (3, 11):
@@ -128,15 +129,45 @@ def generate_yaml_schema(config: list[OptionGroup]):
 
     return json.dumps(root, indent=2, sort_keys=True)
 
-if __name__ == "__main__":
+
+def main():
+    # Parse arguments
+    parser = argparse.ArgumentParser(description="Generate or check the MrDocs YAML schema.")
+    parser.add_argument('--output', type=str, help="Path to the output schema file.")
+    parser.add_argument('--check', action='store_true', default=False,
+                        help="Check if the generated schema matches the existing file.")
+    args = parser.parse_args()
+
+    # Determine the schema path
     mrdocs_root_dir = os.path.join(os.path.dirname(__file__), '..')
-    mrdocs_schema_path = os.path.join(mrdocs_root_dir, 'docs', 'mrdocs.schema.json')
-    mrdocs_config_path = os.path.join(mrdocs_root_dir, 'src', 'lib', 'Lib', 'ConfigOptions.json')
+    default_schema_path = os.path.join(mrdocs_root_dir, 'docs', 'mrdocs.schema.json')
+    mrdocs_schema_path = args.output if args.output else default_schema_path
+    if not os.path.isabs(mrdocs_schema_path):
+        mrdocs_schema_path = os.path.abspath(os.path.join(mrdocs_root_dir, mrdocs_schema_path))
 
+    # Generate the schema
+    mrdocs_config_path = os.path.join(mrdocs_root_dir, 'src', 'lib', 'Lib', 'ConfigOptions.json')
     with open(mrdocs_config_path, 'r') as f:
         config = json.loads(f.read())
-    
     yaml_schema = generate_yaml_schema(config)
 
-    with open(mrdocs_schema_path, 'w') as f:
-        f.write(yaml_schema)
+    if args.check:
+        # Check if the generated schema matches the existing schema
+        with open(mrdocs_schema_path, 'r') as f:
+            existing_schema = f.read()
+        if yaml_schema != existing_schema:
+            print(
+                "The generated schema does not match the existing schema."
+                "Please run `util/generate-yaml-schema.py` to update the schema."
+            )
+            sys.exit(1)
+        else:
+            print("The generated schema matches the existing schema.")
+    else:
+        # Write the schema to the file
+        with open(mrdocs_schema_path, 'w') as f:
+            f.write(yaml_schema)
+
+
+if __name__ == "__main__":
+    main()