Generate gql-errors index.adoc file

modules/ROOT/pages/errors/gql-errors/42N44.adoc

@@ -2,7 +2,7 @@
 
 
 == Status description
-error: syntax error or access rule violation - inaccessible variable. It is not possible to access the variable `{ <<var>> }` declared before the `{ <<clause>> }` clause when using `DISTINCT` or an aggregation.
+error: syntax error or access rule violation - inaccessible variable. It is not possible to access the variable `{ <<variable>> }` declared before the `{ <<clause>> }` clause when using `DISTINCT` or an aggregation.
 
 
 

modules/ROOT/pages/errors/gql-errors/index.adoc

@@ -1,5 +1,5 @@
-// This is an automatically generated file. Do not edit it directly.
-// It is generated from the templates/gql-index-template.adoc file and should be edited there. //// //// //// //// //// ////
+// This is an automatically generated file. Do not edit it directly. It is generated from the templates/gql-index-template.adoc file and should be edited there.
+
 
 :description: This section describes the GQLSTATUS errors that Neo4j can return, grouped by category, and an example of when they can occur.
 
@@ -1013,7 +1013,7 @@ Status description:: error: syntax error or access rule violation - dynamic enti
 
 Status description:: error: syntax error or access rule violation - invalid glob escaping. Each part of the glob (a block of text up until a dot) must either be fully escaped or not escaped at all.
 
-=== xref:errors/gql-errors/42I60.adoc[42I61]
+=== xref:errors/gql-errors/42I61.adoc[42I61]
 
 Status description:: error: syntax error or access rule violation - missing LOOKUP INDEX function name. Missing function name for the LOOKUP INDEX.
 
@@ -1189,7 +1189,6 @@ Status description:: error: syntax error or access rule violation - incompatible
 
 Status description:: error: syntax error or access rule violation - invalid use of `CALL { ... }`. Not possible to enclose `{ <<clause>> }` in `CALL { ... }`. Use `CALL () { ... }` instead.
 
-
 === xref:errors/gql-errors/42N40.adoc[42N40]
 
 Status description:: error: syntax error or access rule violation - single relationship pattern required. The `{ <<fun>> }` function must contain one relationship pattern.

modules/ROOT/templates/gql-index-template.adoc

@@ -1,5 +1,4 @@
-// This is an automatically generated file. Do not edit it directly.
-// It is generated from the templates/gql-index-template.adoc file and should be edited there. //// //// //// //// //// ////
+
 
 :description: This section describes the GQLSTATUS errors that Neo4j can return, grouped by category, and an example of when they can occur.
 

scripts/README.adoc

@@ -13,26 +13,36 @@ This script generates the _auto-index.adoc_ file by using the template in _templ
 
 What it does::
 * Extracts error codes from filenames (e.g., 42007.adoc → 42007).
-Extracts the status descriptions from individual error files.
+* Extracts the status descriptions from individual error files.
 * Extracts page roles from files (`:page-role: changed-2025.04`).
 * Creates a new _auto-index.adoc_ file based on the template and populates it with the extracted data.
 
-=== `validate_error_index.py`
+=== `validate-error-index.py`
 
-This index validates the consistency between _index.adoc_ and individual error files, identifying discrepancies in  Error codes, status descriptions, and page roles.
+This index validates the consistency between _index.adoc_ and individual error files, identifying discrepancies in error codes, status descriptions, and page roles.
 
 What it does::
 * Checks for error codes mentioned in the index.adoc file that don't have corresponding files.
 * Finds error files without index entries.
 * Detects status description mismatches between the index and individual files.
 * Verifies page role consistency.
 
-=== `update-gql-error-index.sh`
+=== `validate-error-auto-index.py`
+
+This index validates the consistency between _auto-index.adoc_ and individual error files, identifying discrepancies in error codes, status descriptions, and page roles.
 
-This script runs the previous two scripts (the generation and validation scripts), and if validation passes, it replaces _index.adoc_ with _auto-index.adoc_.
+What it does::
+* Checks for error codes mentioned in the index.adoc file that don't have corresponding files.
+* Finds error files without index entries.
+* Detects status description mismatches between the index and individual files.
+* Verifies page role consistency.
+
+=== `update-gql-error-index.sh`
+This script orchestrates the execution of the other scripts in a specific order to ensure that the error index is generated and validated correctly.
 
 What it does::
-* Runs the `generate-gql-error-index-from-template.py` script to generate the _auto-index.adoc_ file.
-* Runs the `validate_error_index.py` script to validate the generated file against the individual error files.
-* If validation passes, it replaces the existing _index.adoc_ file with _auto-index.adoc_.
-* If validation fails, it prints an error message and does not replace the _index.adoc_ file, while also keeping the _auto-index.adoc_ file for review.
+1. Runs the validation script to check for discrepancies between the _index.adoc_ file and the individual error files.
+2. If validation passes, it runs the generation script to create the _auto-index.adoc_ file.
+3. Runs the validation script again to check for discrepancies between the _auto-index.adoc_ file and the individual error files.
+4. If validation passes, it replaces the existing _index.adoc_ file with _auto-index.adoc_.
+5. If validation fails, it prints an error message and does not replace the _index.adoc_ file, while also keeping the _auto-index.adoc_ file for manual review.

scripts/generate-gql-error-index-from-template.py

@@ -140,6 +140,7 @@ def generate_from_template(template_file, errors_dir, output_file, include_descr
 
     # Write the result to the output file
     with open(output_file, 'w') as f:
+        f.write("// This is an automatically generated file. Do not edit it directly. It is generated from the templates/gql-index-template.adoc file and should be edited there.\n")
         f.write(template_content)
 
     print(f'Generated index file at: {output_file}')

scripts/update-gql-error-index.sh

@@ -1,12 +1,7 @@
 #!/bin/bash
 
-# Script to generate, validate, and update the GQL error index
-# This script will:
-# 1. Generate auto-index.adoc using the template
-# 2. Validate that it matches the content of index.adoc
-# 3. If validation passes, replace index.adoc with auto-index.adoc
-
-set -e  # Exit on any error
+# Script to validate and update the GQL error index
+# This script follows a specific workflow to maintain error documentation consistency
 
 # Define paths
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
@@ -23,34 +18,50 @@ fi
 
 echo "===== Starting GQL Error Index Update Process ====="
 
-# Step 1: Generate auto-index.adoc
-echo "Generating auto-index.adoc from template..."
-python3 "$SCRIPT_DIR/generate-gql-error-index-from-template.py"
+# Step 1: Validate index.adoc against the individual files
+echo "Step 1: Validating index.adoc against individual files..."
+python3 "$SCRIPT_DIR/validate-error-index.py"
+VALIDATION_RESULT=$?
 
-if [ ! -f "$AUTO_INDEX_FILE" ]; then
-    echo "Error: Failed to generate auto-index.adoc"
-    exit 1
-fi
+# Step 2: Check validation result
+if [ $VALIDATION_RESULT -eq 0 ]; then
+    echo "✅ Validation passed! index.adoc is consistent with individual files."
+    echo "No further action needed."
+    exit 0
+else
+    echo "❌ Validation failed. Checking if there are missing entries..."
 
-echo "Generation completed successfully."
+    # Step 3: Generate auto-index.adoc
+    echo "Step 3: Generating auto-index.adoc from template..."
+    python3 "$SCRIPT_DIR/generate-gql-error-index-from-template.py"
+    GENERATION_RESULT=$?
 
-# Step 2: Validate auto-index.adoc against the files.
-echo "Validating auto-index.adoc against the files and index.adoc..."
-python3 "$SCRIPT_DIR/validate_error_index.py"
-VALIDATION_RESULT=$?
+    if [ $GENERATION_RESULT -ne 0 ] || [ ! -f "$AUTO_INDEX_FILE" ]; then
+        echo "Error: Failed to generate auto-index.adoc"
+        exit 1
+    fi
 
-# Step 3: If validation passes, replace index.adoc with auto-index.adoc
-if [ $VALIDATION_RESULT -eq 0 ]; then
-    echo "Validation passed! Replacing index.adoc with auto-index.adoc..."
+    echo "Generation completed successfully."
 
-    # Replace index with auto-index
-    rm "$INDEX_FILE"
-    mv "$AUTO_INDEX_FILE" "$INDEX_FILE"
+    # Step 4: Validate auto-index.adoc against individual files
+    echo "Step 4: Validating auto-index.adoc against individual files..."
+    python3 "$SCRIPT_DIR/validate-error-auto-index.py"
+    AUTO_VALIDATION_RESULT=$?
 
-    echo "✅ Update completed successfully. index.adoc has been updated."
-else
-    echo "❌ Validation failed with exit code $VALIDATION_RESULT. No changes were made to index.adoc."
-    echo "Please review the validation errors and fix any discrepancies."
-fi
+    # Step 5: If auto-index validation passes, replace index.adoc
+    if [ $AUTO_VALIDATION_RESULT -eq 0 ]; then
+        echo "Step 5: Auto-index validation passed! Replacing index.adoc with auto-index.adoc..."
+
+        # Replace index with auto-index
+        rm "$INDEX_FILE"
+        mv "$AUTO_INDEX_FILE" "$INDEX_FILE"
 
-exit $VALIDATION_RESULT
+        echo "✅ Update completed successfully. index.adoc has been updated."
+        exit 0
+    else
+        echo "❌ Auto-index validation failed with exit code $AUTO_VALIDATION_RESULT."
+        echo "No changes were made to index.adoc."
+        echo "Please review the validation errors and fix any discrepancies."
+        exit $AUTO_VALIDATION_RESULT
+    fi
+fi