generator-validate

name	generator-validate
description	Validate SEA generators produce correct, deterministic output matching their specifications. Use after creating or modifying generators.

Generator Validation

Use this skill when:

• Creating a new SEA generator
• Modifying an existing generator
• Validating generator output correctness
• Checking generator determinism

Validation Process

1. Generator Source Check

Verify the generator source is valid:

# Check generator structure
ls -la generators/bounded-context/
ls -la generators/adapter/

# Validate generator schema
cat generators/bounded-context/schema.json | jq .

# Check generator implementation
cat generators/bounded-context/generator.ts

Required generator components:

• ✅ schema.json - Input validation schema
• ✅ generator.ts or generator.py - Implementation
• ✅ files/ directory - Template files
• ✅ README.md - Documentation

2. Dry Run Validation

Run generator in dry-run mode:

# Nx generator dry run
pnpm exec nx g @sea/bounded-context-generator:gen --dry-run --name=TestContext

# Or with just command
just gen bounded-context --dry-run --name=TestContext

Expected output:

• List of files that would be created
• No actual files created
• Validation passes

3. Determinism Check

Run generator multiple times and verify output is identical:

# First run
rm -rf tmp/gen-test-1
pnpm exec nx g @sea/bounded-context-generator:gen --name=TestGen1 --output-dir=tmp/gen-test-1
find tmp/gen-test-1 -type f -exec sha256sum {} \; > tmp/sha1.txt

# Second run with same input
rm -rf tmp/gen-test-2
pnpm exec nx g @sea/bounded-context-generator:gen --name=TestGen1 --output-dir=tmp/gen-test-2
find tmp/gen-test-2 -type f -exec sha256sum {} \; > tmp/sha2.txt

# Compare
diff tmp/sha1.txt tmp/sha2.txt

Expected: No differences (deterministic output)

4. Output Validation

Validate generated output matches spec:

# Generate actual output
pnpm exec nx g @sea/bounded-context-generator:gen --name=ValidateMe

# Check generated structure
find apps/validate-me -type f

# Validate against spec
# - Check all required files exist
# - Validate file content matches patterns
# - Check imports and references

5. Spec Compliance Check

Verify generated output complies with governing spec:

# Find related spec
find docs/specs -name "*bounded-context*" -o -name "*adapter*"

# Validate with calm if CALM spec
calm validate docs/specs/bounded-context-v1.md

# Check generated output follows spec patterns
# - Architecture matches spec
# - API surface matches spec
# - Naming conventions match

Validation Checklist

• Generator source file exists and is valid
• Schema file exists and validates
• All template files exist
• Dry run completes without errors
• Output is deterministic (same input → same output)
• All expected files are generated
• Generated files have correct content
• Output complies with governing spec
• No unexpected side effects
• Generator documentation is complete

Common Issues

Issue: Non-deterministic output

Symptoms: Different files generated for same input

Causes:

• Using timestamps in generated files
• Using random values
• Using current user/environment

Fix:

• Use deterministic values for generation
• Make timestamps optional
• Use placeholder values

Issue: Missing required files

Symptoms: Expected files not generated

Causes:

• Template file missing from files/ directory
• Template not referenced in generator
• Conditional logic preventing generation

Fix:

• Add missing template files
• Update generator to include all files
• Review conditional logic

Issue: Output doesn't match spec

Symptoms: Generated code differs from specification

Causes:

• Generator and spec diverged
• Template uses wrong patterns
• Spec was updated but generator wasn't

Fix:

• Update generator to match spec
• Update templates to use correct patterns
• Re-run spec validation

Validation Report Template

## Generator Validation Report

**Generator**: {name}
**Version**: {version}
**Date**: {timestamp}

### Source Validation
- Schema: ✅/❌
- Implementation: ✅/❌
- Templates: ✅/❌
- Documentation: ✅/❌

### Dry Run
- Status: ✅/❌
- Files to create: {count}

### Determinism Check
- Status: ✅/❌
- SHA256 match: ✅/❌

### Output Validation
- Files generated: {count}/{expected}
- Content valid: ✅/❌
- Spec compliant: ✅/❌

### Issues Found
{list of issues}

### Recommendation
{pass/fail with notes}

Usage

Invoke after generator changes:

• "Validate the bounded-context generator"
• "Check if adapter generator is working correctly"
• "Run generator validation for all generators"

Claude invokes automatically when:

• Editing generator files
• Committing generator changes
• Running just validate-generators

Integration

• Integrates with spec-guardian for generated zone enforcement
• Integrates with governance-validation for spec compliance
• Integrates with CI/CD for automated validation