replace the script with a new one that generates the index file from a template and populates the codes, update the verification, add bash to automate the workflow, and add a readme

Author: renetapopova

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

@@ -0,0 +1,97 @@
+// 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.
+
+[[neo4j-gqlstatus-errors]]
+= List of GQLSTATUS error codes
+
+The following page provides an overview of all GQLSTATUS server error codes in Neo4j.
+All errors in Neo4j have severity level `ERROR`.
+
+[WARNING]
+====
+Please note that while GQLSTATUS codes remain stable (any changes to them will be breaking), changes to status descriptions associated with these codes are not breaking and may happen at any time.
+For this reason, parsing the status descriptions or incorporating them into scripts is not recommended.
+====
+
+[[connection-exceptions]]
+== Connection exceptions
+
+Connection exceptions occur when the client (e.g. Browser/Bloom/Cypher Shell) is unable to connect to the server for various reasons such as network issues, server-side routing being disabled, or the database being unavailable, etc.
+
+{codes_starting_with:'08'}
+
+[[data-exceptions]]
+== Data exceptions
+
+Database exceptions occur when a client request contains the wrong format, types, or other unsupported input.
+Some examples are data and constraint creation, which conflicts with existing constraints, properties of non-storable type, and spatial and temporal values with invalid components.
+
+{codes_starting_with:'22'}
+
+[[invalid-transaction-state]]
+== Invalid transaction state
+
+Invalid transaction state errors occur when the transaction is in an invalid state, such as when the transaction is terminated or closed, or when there is a conflict between the transaction state and applied updates.
+
+{codes-starting with: '25'}
+
+[[invalid-transaction-termination]]
+== Invalid transaction termination
+
+Invalid transaction termination errors occur when the transaction termination fails, such as when the transaction or constituent transaction fails to commit, or when the transaction termination fails to apply or append the transaction.
+
+{codes-starting with: '2D'}
+
+[[transaction-rollback]]
+== Transaction rollback
+
+Transaction rollback errors occur when there is a failure in a transaction or a constituent transaction rollback.
+
+{codes-starting with: '40'}
+
+[[syntax-error-or-access-rule-violation]]
+== Syntax error or access rule violation
+
+Syntax error or access rule violation errors occur when a Cypher query contains invalid syntax or when a client request violates the access rules, such as when a query tries to access a database without enough privileges, etc.
+
+{codes-starting with: '42'}
+
+[[general-processing-exceptions]]
+== General processing exceptions
+
+General processing exceptions occur when there is a general processing error, such as an internal error, deadlock, execution failure, invalid server state transition, constraint creation or drop failure, etc.
+
+{codes-starting with: '50'}
+
+[[system-configuration-or-operation-exceptions]]
+== System configuration or operation exceptions
+
+System configuration or operation exception errors occur when there is an error in the system configuration or operation, such as procedure registration failure, a missing class field annotation, an unsupported injectable component type, duplicate field names, invalid map key type, etc.
+
+{codes-starting with: '51'}
+
+[[procedure-exceptions]]
+== Procedure exceptions
+
+Procedure exceptions occur when there is an error in executing a procedure, such as when the procedure execution fails due to a client error, when the procedure cannot be invoked on a primary, when the number of arguments to checkConnectivity is invalid, etc.
+
+{codes-starting with: '52'}
+
+[[function-exceptions]]
+== Function exceptions
+
+{codes-starting with: '53'}
+
+[[dependent-object-errors]]
+== Dependent object errors
+
+{codes-starting with: 'G1'}
+
+ifndef::backend-pdf[]
+[discrete.glossary]
+== Glossary
+
+include::partial$glossary.adoc[]
+endif::[]

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

@@ -0,0 +1,38 @@
+= Scripts for generating and validating gql error index.adoc file
+
+This folder contains utility scripts for generating and validating gql error index.adoc file.
+
+== Scripts overview
+
+The folder contains the following scripts:
+
+
+=== `generate-gql-error-index-from-template.py`
+
+This script generates the _auto-index.adoc_ file by using the template in _templates/gql-index-template.adoc_ and populating it with error codes from the individual files located in the _gql-errors_ directory.
+
+What it does::
+* Extracts error codes from filenames (e.g., 42007.adoc → 42007).
+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`
+
+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`
+
+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::
+* 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.

scripts/README.adoc

@@ -0,0 +1,184 @@
+#!/usr/bin/env python3
+
+import os
+import re
+from pathlib import Path
+import argparse
+
+# For debugging - examine a single file to understand its structure
+def examine_error_file(file_path):
+    """Print the contents of an error file for debugging."""
+    try:
+        with open(file_path, 'r') as f:
+            content = f.read()
+            print(f"=== File Content for {file_path.name} ===")
+            print(content)
+            print("===================================")
+
+            # Try to extract the description with different patterns
+            patterns = [
+                r'Status description::\s*(.*?)(?=\n\n|\n==|\Z)',
+                r'== Status description\s*\n(.*?)(?=\n\n|\n==|\Z)',
+                r'== Status description\s*\n\s*Status description:: (.*?)(?=\n\n|\n==|\Z)'
+            ]
+
+            for i, pattern in enumerate(patterns):
+                match = re.search(pattern, content, re.DOTALL)
+                if match:
+                    print(f"Pattern {i+1} matched! Description: {match.group(1)[:50]}...")
+                else:
+                    print(f"Pattern {i+1} did not match")
+    except Exception as e:
+        print(f"Error reading file: {e}")
+
+def get_error_codes_from_files(errors_dir, verbose=False):
+    """Get all error codes and their details from individual .adoc files."""
+    error_codes = {}
+    sample_file = None
+
+    for file in os.listdir(errors_dir):
+        if file.endswith('.adoc') and file != 'index.adoc' and file != 'auto-index.adoc':
+            error_code = file[:-5]  # Remove .adoc extension
+            file_path = os.path.join(errors_dir, file)
+
+            if sample_file is None:
+                sample_file = file_path  # Save first file for debugging
+
+            # Extract details from file
+            with open(file_path, 'r') as f:
+                content = f.read()
+
+                # Extract page role
+                page_role = None
+                role_match = re.search(r':page-role:\s*(.*?)(?=\n|\Z)', content)
+                if role_match:
+                    page_role = role_match.group(1).strip()
+
+                # Extract description - try several patterns
+                description = None
+                desc_patterns = [
+                    r'Status description::\s*(.*?)(?=\n\n|\n==|\Z)',  # Simple format
+                    r'== Status description\s*\n\s*Status description:: (.*?)(?=\n\n|\n==|\Z)',  # Section + desc
+                    r'== Status description\s*\n(.*?)(?=\n\n|\n==|\Z)'  # Section only
+                ]
+
+                for pattern in desc_patterns:
+                    match = re.search(pattern, content, re.DOTALL)
+                    if match:
+                        description = match.group(1).strip()
+                        break
+
+            error_codes[error_code] = {
+                'description': description,
+                'page_role': page_role
+            }
+
+            if verbose and description:
+                print(f"Found description for {error_code}: {description[:50]}...")
+            elif verbose:
+                print(f"No description found for {error_code}")
+
+    # If we didn't find any descriptions, examine a sample file
+    if verbose and sample_file and not any(code['description'] for code in error_codes.values()):
+        print("\nNo descriptions were found in any files. Examining a sample file:")
+        examine_error_file(sample_file)
+
+    return error_codes
+
+def generate_from_template(template_file, errors_dir, output_file, include_descriptions=True, verbose=False):
+    """Generate the index file from template and individual error files."""
+    if verbose:
+        print("Extracting error codes and descriptions...")
+
+    # Get error codes and their info with improved extraction
+    error_codes = get_error_codes_from_files(errors_dir, verbose)
+
+    if verbose:
+        desc_count = sum(1 for code in error_codes.values() if code['description'])
+        print(f"Found {len(error_codes)} error code files, {desc_count} with descriptions")
+
+    # Read the template
+    with open(template_file, 'r') as f:
+        template_content = f.read()
+
+    # Define patterns to find placeholders
+    patterns = [
+        r'\{codes_starting_with:\'([^\']+)\'\}',
+        r'\{codes-starting with: \'([^\']+)\'\}'
+    ]
+
+    # Replace placeholders with generated content
+    for pattern in patterns:
+        for match in re.finditer(pattern, template_content):
+            prefix = match.group(1)
+            placeholder = match.group(0)
+
+            if verbose:
+                print(f"Processing prefix: {prefix}")
+
+            # Generate content for this prefix
+            content = []
+            matching_codes = [code for code in sorted(error_codes.keys()) if code.startswith(prefix)]
+
+            for error_code in matching_codes:
+                # Add page role if exists
+                if error_codes[error_code]['page_role']:
+                    content.append(f'[role=label--{error_codes[error_code]["page_role"]}]')
+
+                content.append(f'=== xref:errors/gql-errors/{error_code}.adoc[{error_code}]')
+                content.append('')
+
+                # Add description if available and requested
+                if include_descriptions and error_codes[error_code]['description']:
+                    content.append(f'Status description:: {error_codes[error_code]["description"]}')
+                    content.append('')
+
+            section_content = '\n'.join(content)
+
+            # Replace placeholder with generated content
+            template_content = template_content.replace(placeholder, section_content)
+
+    # Write the result to the output file
+    with open(output_file, 'w') as f:
+        f.write(template_content)
+
+    print(f'Generated index file at: {output_file}')
+    print(f'Used template: {template_file}')
+    print(f'Total error codes processed: {len(error_codes)}')
+
+def main():
+    # Set up argument parser
+    parser = argparse.ArgumentParser(description='Generate GraphQL error code index from template')
+    parser.add_argument('--no-descriptions', action='store_true',
+                      help='If set, only error codes will be listed without their descriptions')
+    parser.add_argument('--verbose', action='store_true',
+                      help='Show detailed information during processing')
+    parser.add_argument('--debug-file', help='Debug a specific error file')
+    args = parser.parse_args()
+
+    # Get the script's directory
+    script_dir = Path(__file__).parent.absolute()
+
+    # Navigate to the required directories
+    errors_dir = script_dir.parent / 'modules' / 'ROOT' / 'pages' / 'errors' / 'gql-errors'
+    template_file = script_dir.parent / 'modules' / 'ROOT' / 'templates' / 'gql-index-template.adoc'
+    output_file = errors_dir / 'auto-index.adoc'
+
+    # Debug specific file if requested
+    if args.debug_file:
+        debug_path = errors_dir / f"{args.debug_file}.adoc"
+        if debug_path.exists():
+            examine_error_file(debug_path)
+        else:
+            print(f"Error: Debug file not found at {debug_path}")
+        return
+
+    if not template_file.exists():
+        print(f"Error: Template file not found at {template_file}")
+        return
+
+    generate_from_template(template_file, errors_dir, output_file,
+                          not args.no_descriptions, args.verbose)
+
+if __name__ == '__main__':
+    main()