Struct Config 

pub struct Config {
    pub defaults: Defaults,
    pub selectors: Selectors,
    pub runner: RunnerConfig,
    pub llm: LlmConfig,
    pub phases: PhasesConfig,
    pub hooks: HooksConfig,
    pub security: SecurityConfig,
    pub source_attribution: HashMap<String, ConfigSource>,
}

Configuration for xchecker operations.

Config provides hierarchical configuration with discovery and precedence: CLI arguments > config file > built-in defaults.

Discovery

Use Config::discover() for CLI-like behavior that:

• Searches for .xchecker/config.toml upward from current directory
• Respects the XCHECKER_HOME environment variable
• Applies built-in defaults for unspecified values

Programmatic Configuration

For embedding scenarios where you need deterministic behavior independent of the user’s environment, construct a Config directly or use xchecker::OrchestratorHandle::from_config().

Source Attribution

Each configuration value tracks its source (cli, config, programmatic, or default) for debugging and status display.

Example

use xchecker_config::Config;
use xchecker_config::CliArgs;

// Discover configuration using CLI semantics
let config = Config::discover(&CliArgs::default())?;

// Access configuration values
println!("Model: {:?}", config.defaults.model);
println!("Max turns: {:?}", config.defaults.max_turns);

Configuration File Format

Configuration files use TOML format with these sections:

[defaults]
model = "haiku"
max_turns = 6
phase_timeout = 600

[selectors]
include = ["**/*.md", "**/*.yaml"]
exclude = ["target/**", "node_modules/**"]

[runner]
mode = "auto"

[llm]
provider = "claude-cli"

Fields

defaults: Defaults

Default values for various settings.

selectors: Selectors

File selection patterns for packet building.

runner: RunnerConfig

Runner configuration for cross-platform execution.

llm: LlmConfig

LLM provider configuration.

phases: PhasesConfig

Per-phase configuration overrides.

hooks: HooksConfig

Hooks configuration for pre/post phase scripts.

security: SecurityConfig

Security configuration for secret detection and redaction.

source_attribution: HashMap<String, ConfigSource>

Source attribution for each setting (for status display).

Implementations

impl Config

pub fn builder() -> ConfigBuilder

Create a builder for programmatic configuration.

Use this when you need to configure xchecker programmatically without relying on environment variables or config files. This is the recommended approach for embedding xchecker in other applications.

Example

use xchecker_config::Config;
use std::time::Duration;

let config = Config::builder()
    .state_dir("/custom/path")
    .packet_max_bytes(32768)
    .packet_max_lines(600)
    .phase_timeout(Duration::from_secs(300))
    .build()
    .expect("Failed to build config");

impl Config

pub fn discover(cli_args: &CliArgs) -> Result<Config, XCheckerError>

Discover and load configuration with precedence: CLI > file > defaults

Uses current working directory for config file discovery when no explicit path is provided in cli_args.

pub fn discover_from( start_dir: &Path, cli_args: &CliArgs, ) -> Result<Config, XCheckerError>

Discover and load configuration starting from a specific directory

This is the path-driven variant used by tests to avoid process-global state. Uses the given directory for config file discovery when no explicit path is provided in cli_args.

pub fn discover_config_file_from( start_dir: &Path, ) -> Result<Option<PathBuf>, XCheckerError>

Discover config file by searching upward from a given directory

This is the path-driven variant used by tests to avoid process-global state. Walks up the directory tree looking for .xchecker/config.toml, stopping at repository root markers (.git, .hg, .svn) or filesystem root.

pub fn discover_from_env_and_fs() -> Result<Config, XCheckerError>

Discover configuration from environment and filesystem.

This method uses the same discovery logic as the CLI:

• XCHECKER_HOME environment variable (if set)
• Upward search for .xchecker/config.toml from current directory
• Built-in defaults

Precedence: config file > defaults

This is the recommended method for library consumers who want CLI-like behavior without needing to construct CliArgs.

Example

use xchecker_config::Config;

let config = Config::discover_from_env_and_fs()
    .expect("Failed to discover config");

Errors

Returns an error if:

• The current directory cannot be determined
• A config file exists but cannot be parsed
• Configuration validation fails

impl Config

pub fn effective_config(&self) -> HashMap<String, (String, String)>

Get effective configuration as key-value pairs with source attribution

impl Config

pub fn get_runner_mode(&self) -> Result<RunnerMode, XCheckerError>

Convert runner mode string to enum

pub fn model_for_phase(&self, phase: PhaseId) -> String

Get the model to use for a specific phase.

Precedence (highest to lowest):

1. Phase-specific override ([phases.<phase>].model)
2. Global default ([defaults].model)
3. Hard default: "haiku" (fast, cost-effective for testing/development)

Example

[defaults]
model = "haiku"

[phases.design]
model = "sonnet"

[phases.tasks]
model = "sonnet"

With the above config:

• model_for_phase(Requirements) -> “haiku”
• model_for_phase(Design) -> “sonnet”
• model_for_phase(Tasks) -> “sonnet”

pub fn strict_validation(&self) -> bool

Check if strict validation is enabled.

When strict validation is enabled, phase output validation failures (meta-summaries, too-short output, missing required sections) become hard errors that fail the phase. When disabled, validation issues are logged as warnings only.

Returns

Returns true if strict validation is enabled, false otherwise. Defaults to false if not explicitly configured.

Trait Implementations

impl Clone for Config

fn clone(&self) -> Config

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Config

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl SecretConfigProvider for Config

fn extra_secret_patterns(&self) -> &[String]

fn ignore_secret_patterns(&self) -> &[String]