# Random Wasot File Generator

The Wasot compiler includes a built-in random file generator that creates syntactically valid Wasot files with random content. This is useful for [testing](./testing.md), fuzzing, and stress-testing tools that process Wasot files. For memory usage analysis with large generated files, see [memory analysis](./memory_analysis.md). For [CLI](./cli.md) usage, see the CLI documentation.

## Usage

### Basic Usage

Generate a random Wasot file with 100 events (default):
```bash
cargo run -- random
```

### Specify Event Count

Generate a file with a specific number of events:
```bash
cargo run -- random -n 500
```

### Save to File

Save the output to a file instead of printing to stdout:
```bash
cargo run -- random -n 200 -o test.wasot
```

### Reproducible Output

Use a seed for deterministic output (useful for testing):
```bash
cargo run -- random -n 100 -s 42
```

This will always generate the same output when run with the same seed.

## Examples

### Generate a small test file
```bash
cargo run -- random -n 50 -o small-test.wasot
```

### Generate a large file for performance testing
```bash
cargo run -- random -n 10000 -o large-test.wasot
```

### Generate and validate in one command
```bash
cargo run -- random -n 100 | cargo run -- xml-listener /dev/stdin | cargo run -- validate
```

### Generate and convert to XML
```bash
cargo run -- random -n 100 | cargo run -- xml-listener /dev/stdin --pretty
```

## What Gets Generated

The random generator creates:

1. **Meta-lines** with:
   - Random block types (p, div, section, heading, code, etc.)
   - Random nesting levels (1-4 dots)
   - Optional inline text
   - Optional parameters (positional and key-value)
   - Optional IDs

2. **Text content** with:
   - Pseudo-words that look like text
   - Multiple lines of content
   - Varied line lengths

3. **Proper structure**:
   - All opened blocks are properly closed
   - Valid nesting
   - Syntactically correct Wasot format

## Implementation Details

The random generator implements an [emitter](./architecture.md) that produces events. It uses a weighted distribution:
- 50% chance of generating a BlockStarted event
- 30% chance of generating a TextFinished event
- 20% chance of generating a BlockFinished event

This ensures a good mix of content while maintaining valid structure.

## Testing with Random Files

The random generator is particularly useful for:

1. **Fuzz testing**: Generate many random files to test parser robustness
2. **Performance testing**: Create large files to measure processing speed
3. **Roundtrip testing**: Verify that files can be parsed and reconstructed
4. **Tool testing**: Test downstream tools with varied input

Example testing workflow:
```bash
# Generate 100 random files for testing
for i in {1..100}; do
    cargo run -- random -n 1000 -o "test-$i.wasot"
done

# Test roundtrip conversion
for file in test-*.wasot; do
    cargo run -- to-sqlite "$file" -d test.db
    cargo run -- from-sqlite -d test.db -o "roundtrip-$file"
    diff "$file" "roundtrip-$file" || echo "Difference found in $file"
done
```