helix-db/hql-tests/README.md

HQL Tests Runner

A test runner for processing helix files with automatic GitHub issue creation for errors.

Features

• Process individual helix files or all files (1-100) in parallel
• Automatic GitHub issue creation for compilation and cargo check errors
• Duplicate issue prevention using error hashing
• Clean temporary directory management

Usage

Basic Usage

# Process all files in parallel
cargo run --bin test

# Process a specific file
cargo run --bin test -- 42

GitHub Integration

To enable automatic GitHub issue creation, set the following environment variables:

export GITHUB_TOKEN="your_personal_access_token"
export GITHUB_OWNER="HelixDB"           # Optional, defaults to "HelixDB"
export GITHUB_REPO="helix-db"           # Optional, defaults to "helix-db"

Creating a GitHub Personal Access Token

1. Go to GitHub Settings → Developer settings → Personal access tokens
2. Generate a new token with the following permissions:
   • repo (Full control of private repositories)
   • issues (Read and write access to issues)
3. Copy the token and set it as the GITHUB_TOKEN environment variable

How Issue Creation Works

When an error occurs during processing:

1. Error Hashing: A unique hash is generated from the error type and message
2. Duplicate Check: The system searches for existing issues with the same error hash
3. Issue Creation: If no duplicate exists, a new issue is created with:
   • Descriptive title including error type and file number
   • Detailed error information in the body
   • Automatic labels: bug, automated, hql-tests
   • Unique error hash for duplicate prevention

Error Types Handled

• Helix Compilation Errors: Issues created when helix compile fails
• Cargo Check Errors: Issues created when cargo check fails

Example Issue

Title: Auto-generated: Helix Compilation Error in file42

Body:
## Automatic Error Report

**Error Type:** Helix Compilation
**File:** file42
**Error Hash:** ERROR_HASH:abc123def456

### Error Details

[Error output details]

---
*This issue was automatically generated by the hql-tests runner.*

Requirements

• Rust 1.70+
• helix CLI tool installed
• GitHub personal access token (for issue creation)
• Internet connection (for GitHub API calls)

Dependencies

• tokio - Async runtime
• clap - Command line argument parsing
• anyhow - Error handling
• octocrab - GitHub API client
• sha2 - Error hashing
• base64 - Hash encoding