# SpacetimeDB SDK Client Comparison Tool

Compares client code generated from Rust and C++ bindings modules to validate type system equivalence and catch regressions.

## Quick Start

```bash
./run_client_comparison.sh
```

This builds the C++ module, regenerates clients, and runs both client and module schema comparisons.

## How It Works

**3-Step Process:**
1. **Build & Regenerate**: Compiles `lib.cpp` and generates fresh C++ client
2. **Compare**: Runs client code and module schema comparisons in parallel  
3. **Summarize**: Shows statistics and generates detailed analysis files

**Prerequisites:**
- SpacetimeDB CLI: `cargo build --release -p spacetimedb-cli`

**Output:**
- `client_diff_analysis.txt` - Detailed client code differences
- `module_diff_analysis.txt` - Module schema comparison
- Console summaries with key metrics

## Scripts

### `run_client_comparison.sh` (Main)
Complete workflow: build → regenerate → compare → summarize

### `scripts/compare_clients.sh`
Client code comparison with intelligent filtering:
- Ignores paths, version comments, whitespace
- Shows only meaningful code differences
- Provides accurate file statistics

### `scripts/compare_modules.sh`
Module schema comparison:
- Publishes WASM to temporary databases
- Extracts schemas via `spacetime describe --json`
- Compares typespace, tables, reducers, named types

### `scripts/regenerate_cpp_client.sh`
Rebuilds C++ client only (no comparison)

## Understanding Results

**Client Comparison:**
- **File counts**: Total files generated by each SDK
- **Identical files**: Files with no meaningful differences (after filtering)
- **Difference types**: Type representations, imports, structure flattening

**Module Schema:**
- **Typespace**: Core type definitions and relationships
- **Common differences**: Registration order, duplicates, special type handling

## Usage

**Standard workflow:**
```bash
cd crates/bindings-cpp/tests/client-comparison
./run_client_comparison.sh
```

**Update baselines:**
```bash
# Rust baseline
cd rust-sdk-test
spacetime generate --lang rust --out-dir . --module-path ../../../modules/sdk-test

# Rust baseline
./scripts/regenerate_rust_client.sh

# C++ baseline  
./scripts/regenerate_cpp_client.sh
```

## Troubleshooting

- **"CLI not found"**: Build CLI with `cargo build --release -p spacetimedb-cli`
- **"Client generation failed"**: Check if lib.cpp publishes successfully
- **"No differences"**: Normal if no changes were made

The tool validates C++ bindings functionality by comparing generated client code and module schemas against the Rust SDK baseline.