Module validate

Source
Expand description

§Configuration Validation Command

The validate command checks a configuration file for correctness without producing any output files. It performs both syntactic validation (is it valid TOML?) and semantic validation (are the values sensible?).

§Usage

# Validate default config location
fernctl validate

# Validate specific file
fernctl validate --config ./my-config.toml

# With verbose output
fernctl validate -v

§Validation Stages

Validation proceeds in three stages:

┌─────────────┐    ┌──────────────┐    ┌────────────────┐
│   Stage 1   │───▶│   Stage 2    │───▶│    Stage 3     │
│   Parsing   │    │  Type Check  │    │   Semantics    │
└─────────────┘    └──────────────┘    └────────────────┘
    TOML syntax       Value types        Business rules
    Well-formed       Color formats      Range limits
    Structure         Required fields    Consistency

§Stage 1: Parsing

Checks that the file is syntactically valid TOML:

  • Proper key-value syntax
  • Balanced brackets and quotes
  • Valid escape sequences

Errors at this stage:

  • fern::config::parse_error — Invalid TOML syntax

§Stage 2: Type Checking

Validates that values have the expected types:

  • Numbers where numbers are expected
  • Strings where strings are expected
  • Required fields are present

Errors at this stage:

  • fern::config::type_mismatch — Wrong value type
  • fern::config::missing_field — Required field absent

§Stage 3: Semantic Validation

Checks business rules and constraints:

  • Color values are valid hex (#RRGGBB or #RRGGBBAA)
  • Numbers are within allowed ranges
  • Enum values are recognized ("top", "bottom", etc.)

Errors at this stage:

  • fern::config::invalid_color — Malformed color value
  • fern::config::out_of_range — Number outside limits
  • fern::config::unknown_key — Unrecognized configuration key

§Warnings vs Errors

Not all problems are fatal. The validator distinguishes:

SeverityBehaviorExample
ErrorValidation failsInvalid color format
WarningValidation passes, issue reportedUnknown key

Warnings allow forward compatibility — new config files may have keys that older fernctl versions don’t recognize.

§Exit Codes

CodeMeaning
0Validation passed (possibly with warnings)
1Validation failed with errors

§Programmatic Usage

ⓘ
use fernctl::commands::validate::{run, ValidateOptions};
use fernctl::adapters::TomlConfigAdapter;

let adapter = TomlConfigAdapter::new();
let options = ValidateOptions { verbose: true };

match run(&path, options, &adapter) {
    Ok(result) => {
        println!("Valid! {} warnings", result.warnings.len());
    }
    Err(e) => {
        eprintln!("Invalid: {}", e);
    }
}

Structs§

ValidateOptions
Options for the validate command.
ValidateResult
Result of a successful validation.

Functions§

run
Validates a configuration file.