Diff Core Feature Summary V1

[asadijabar]

Context

Diff Core v1 extends Rigging's snapshot capabilities to compare configuration states across time and environments. Diffs identify added, removed, and changed fields between snapshots, enabling users to answer "What changed between release X and Y?" and "Why is staging fine but prod is broken?"

What you must know

• Diff: Comparison result showing added, removed, and changed fields between two snapshots
• FieldChange: Single field modification with old/new values and severity level
• Severity: Change importance categorization (critical, high, medium, low)
• Baseline: Approved reference snapshot for drift detection
• Drift: Configuration differences from an approved baseline
• Violation: Disallowed difference when comparing against baseline

What are going to be implemented

1. Computing Diffs

What: Compare two snapshots to identify configuration changes.

How: ComputeDiff analyzes snapshot pairs and produces:

• Added fields (present in new, absent in old)
• Removed fields (present in old, absent in new)
• Changed fields (different values between snapshots)
• Severity assignment for each change
• Comparison metadata (timestamps, hostnames, deployment IDs)

Returns an error if snapshots have incompatible versions or invalid structure.

2. Severity Categorization

What: Classify changes by importance for programmatic filtering.

How:

• Default severity rules map field patterns to levels (e.g., *.password → critical, *.timeout → medium)
• Custom severity rules override defaults via DiffOptions.SeverityRules
• Each FieldChange includes its assigned severity
• Unmatched fields default to "low" severity

3. Field Filtering

What: Exclude irrelevant fields from diff results.

How:

• DiffOptions.IgnoreFields removes specified field paths from comparison
• DiffOptions.IgnoreRedacted skips all fields marked as secrets
• Filtering applies before severity assignment
• Without filters, all fields are compared

4. Secret Redaction

What: Prevent secret exposure in diff output.

How:

• Secret fields (from provenance metadata) show ***redacted*** instead of actual values
• Redaction applies to both old and new values in FieldChange
• FieldChange.Secret flag indicates redacted fields
• Redaction occurs during diff formatting, not computation

5. Text Output Format

What: Human-readable diff summary for terminal display.

How: FormatDiff with FormatText produces:

• Header with snapshot metadata (versions, timestamps, hostnames)
• Grouped sections: Added, Removed, Changed
• Per-field lines showing old → new values with severity tags
• Summary line with change counts by severity

Returns formatted string or error if diff is invalid.

6. JSON Output Format

What: Machine-readable diff structure for automation.

How: FormatDiff with FormatJSON serializes:

• Complete Diff struct with all fields
• Nested arrays for added/removed/changed
• Full metadata for both snapshots
• Comparison timestamp

Returns JSON bytes or error if serialization fails.

7. Baseline Validation

What: Detect configuration drift from approved baseline.

How: BaselineValidator compares runtime config against baseline:

• Loads baseline snapshot with signature verification
• Computes diff between baseline and current config
• Applies allowed drift rules (field paths permitted to differ)
• Returns BaselineResult with validity status and violations
• FailOnDrift option determines if any drift causes validation failure

Returns error if baseline signature is invalid or snapshot is corrupted.

8. Baseline Violations

What: Identify critical differences from approved configuration.

How:

• BaselineViolation captures each disallowed difference
• Includes field path, expected value, actual value, and severity
• Violations exclude fields in AllowedDrifts list
• Critical/high severity violations highlighted in results
• Empty violations array indicates valid configuration

9. Loader Integration

What: Automatic baseline validation during configuration loading.

How:

• WithBaselineSnapshot option adds validation to Loader[T]
• Validation runs after struct binding but before returning config
• Validation failures return ValidationError with violations
• Successful validation logs result and continues
• No performance impact when baseline not configured