provisioning-platform/prov-ecosystem/crates/valida/README.md

# Valida - Validation Rules Engine

A centralized validation framework for CI/CD pipelines with context-aware enforcement across different deployment phases.

## Overview

Valida provides a flexible, extensible validation system that enforces rules at different stages of your CI/CD pipeline:
- **Commit** - Pre-commit hooks
- **Build** - Build-time validation
- **Test** - Test phase validation
- **Deploy** - Deployment pre-checks
- **Staging** - Staging environment validation
- **Production** - Production readiness checks

## Features

- 📋 **Context-Aware Validation** - Different rules enforce at different CI/CD phases
- 🏷️ **Rule Categories** - Organize rules by Security, Resources, Network, Environment
- 📊 **Severity Levels** - Error, Warning, Info with blocking/non-blocking modes
- 💾 **Multi-Format Storage** - Load rules from YAML, JSON, or TOML
- 📤 **Multi-Format Export** - Export rules to JSON, YAML, or TOML
- 🔧 **Flexible Rule Definitions** - Regex patterns, thresholds, custom logic
- ✨ **Builder Pattern** - Fluent API for configuration

## Installation

Add to your `Cargo.toml`:

```toml
[dependencies]
valida = "0.1.0"
```

## Quick Start

```rust
use valida::{ValidationRule, RuleSet, RuleSeverity, CIPhase};

// Create a validation rule
let rule = ValidationRule::new("SEC001", "No Hardcoded Secrets")
    .with_severity(RuleSeverity::Error)
    .with_applies_to(vec![CIPhase::Commit, CIPhase::Build])
    .with_pattern(r"(password|secret|api_key)\s*=\s*['\"]?[^'\"\s]+['\"]?");

// Create a rule set
let ruleset = RuleSet::new()
    .add_rule(rule);

// Export to different formats
let json = ruleset.export_json()?;
let yaml = ruleset.export_yaml()?;
let toml = ruleset.export_toml()?;
```

## Rule Categories

- **Security** - Secret management, encryption, authentication
- **Resources** - Memory, CPU, disk limits
- **Network** - Port validation, connectivity checks
- **Environment** - Environment variable requirements, configuration

## CI/CD Phases

Rules are enforced at different phases:

1. **Commit** - Code is committed
2. **Build** - Build process runs
3. **Test** - Tests execute
4. **Deploy** - Deployment begins
5. **Staging** - Staging environment
6. **Production** - Production environment

## Configuration

Load rules from files:

```rust
use valida::load_rules;

// Load from YAML
let rules = load_rules("rules.yaml")?;

// Load from JSON
let rules = load_rules("rules.json")?;

// Load from TOML
let rules = load_rules("rules.toml")?;
```

## Use Cases

### CI/CD Pipeline Validation
Enforce security and resource requirements at each pipeline stage

### Pre-Commit Hooks
Validate commits before they're pushed

### Build Validation
Ensure build artifacts meet requirements

### Deployment Checks
Validate infrastructure before deployments

### Compliance Enforcement
Ensure regulatory and security compliance

## Architecture

- `error.rs` - Error types and result types
- `context.rs` - CI/CD phase definitions and ordering
- `category.rs` - Rule categories and severity levels
- `rule.rs` - Rule definitions and collections
- `storage.rs` - Load rules from various formats
- `export.rs` - Export rules to various formats

## Testing

Run tests with:

```bash
cargo test --lib
```

All 26 tests pass with full coverage of:
- Rule creation and configuration
- Phase ordering and enforcement
- Category and severity handling
- YAML/JSON/TOML loading and exporting
- Rule filtering and validation

## Performance

- Fast rule evaluation
- Minimal memory overhead
- Optimized pattern matching
- Supports thousands of rules

## API Documentation

Full API documentation available with:

```bash
cargo doc --open
```

## Integration

Valida can be integrated with:
- CI/CD systems (GitHub Actions, GitLab CI, Jenkins)
- Build tools (cargo, make, bazel)
- Deployment systems (provctl, provisioning)
- Custom automation scripts

## License

Same as prov-ecosystem parent project

## Contributing

Contributions welcome! See parent project guidelines.

## See Also

- [prov-ecosystem README](../../README.md) - Parent project overview
- [encrypt](../encrypt/README.md) - Encryption crate
- [runtime](../runtime/README.md) - Container runtime abstraction
- [init-servs](../init-servs/README.md) - Init system abstraction