<!-- file: kb-config/USAGE.md -->
<!-- version: 4 -->

# Utilisation de kb-config

## Chargement recommandé

```rust
let config_result = kb_config::read_config_json_file_with_environment(
    std::path::Path::new("config/example.config.json"),
    std::path::Path::new("."),
);
let config = match config_result {
    Ok(value) => value,
    Err(error) => return Err(error),
};
let profile = match kb_config::active_profile(&config) {
    Ok(value) => value,
    Err(error) => return Err(error),
};
```

Cette fonction charge l’environnement du workspace, résout les placeholders puis applique successivement le schéma JSON, la désérialisation typée et les invariants métier.

## Chargement de l’environnement

```rust
let report = match kb_config::load_workspace_environment(std::path::Path::new(".")) {
    Ok(value) => value,
    Err(error) => return Err(error),
};

for path in report.loaded_files {
    println!("environment file: {}", path.display());
}
```

`EnvironmentLoadReport` indique les fichiers chargés. Les placeholders non résolus sans fallback restent visibles afin que la validation ou le consommateur puisse les signaler explicitement. Le format `0.4.8` accepte encore les anciens noms d’environnement ; la migration `0.5.1` imposera le namespace `KS_*`.

## Résolution explicite des placeholders

```rust
let raw = r#"{"databaseUrl":"${KB_DATABASE_URL:-postgres://localhost/kb}"}"#;
let resolved = kb_config::resolve_environment_placeholders(raw);

assert!(resolved.contains("databaseUrl"));
```

Cette API retourne actuellement une chaîne résolue ordinaire et peut donc contenir des secrets issus de l’environnement. Elle doit rester strictement backend et ne doit pas être utilisée pour afficher, logger ou transmettre le JSON résolu. `0.5.1` remplacera cette frontière par une résolution conservant la classification de sensibilité.

## Validation et parsing

```rust
if let Err(error) = kb_config::validate_config_json_schema(raw_json) {
    return Err(error);
}
let config = match kb_config::parse_config_json(raw_json) {
    Ok(value) => value,
    Err(error) => return Err(error),
};
if let Err(error) = kb_config::validate_config(&config) {
    return Err(error);
}
```

`parse_config_json` effectue déjà les deux validations ; les appels séparés servent aux outils de diagnostic.

## Sérialisation

```rust
let compact = match kb_config::serialize_config_json(&config) {
    Ok(value) => value,
    Err(error) => return Err(error),
};
let pretty = match kb_config::serialize_config_json_pretty(&config) {
    Ok(value) => value,
    Err(error) => return Err(error),
};

let write_result = std::fs::write("config/generated.config.json", pretty);
if let Err(error) = write_result {
    return Err(kb_core::Error::new(
        "config_write_failed",
        format!("cannot write generated configuration: {error}"),
    ));
}
```

La configuration est validée avant sérialisation.

## Schéma embarqué

```rust
let schema_text = kb_config::config_json_schema_text();
let schema_value = match kb_config::config_json_schema_value() {
    Ok(value) => value,
    Err(error) => return Err(error),
};

let property_count = schema_value
    .get("properties")
    .and_then(serde_json::Value::as_object)
    .map_or(0, serde_json::Map::len);

println!("embedded schema bytes={}, properties={property_count}", schema_text.len());
```

Le schéma actif est aussi disponible sous [`../config/schema.config.json`](../config/schema.config.json). Le fichier [`../config/example.config.json`](../config/example.config.json) fournit un exemple utilisateur complet.

## Sélection du profil actif

```rust
let profile = match kb_config::active_profile(&config) {
    Ok(value) => value,
    Err(error) => return Err(error),
};

println!("active profile: {}", profile.name);
println!("http endpoints: {}", profile.solana.http_endpoints.len());
println!("websocket endpoints: {}", profile.solana.ws_endpoints.len());
```

## Types publics importants

- `AppConfig`, `ProfileConfig`, `AppSectionConfig` ;
- `DatabaseConfig`, `PostgresConfig`, `SqliteConfig`, `DataConfig` ;
- `SolanaConfig`, `HttpEndpointConfig`, `WsEndpointConfig`, `EndpointRoleConfig` ;
- `ListenerConfig` et ses variantes ;
- `LoggingConfig`, `LogTargetConfig`, `LogTargetFilterConfig` ;
- `WalletConfig`, `ExecutionConfig`, `DemoConfig`.

## Erreurs et invariants

Les erreurs utilisent `kb_core::Error` avec un code stable. Les validations couvrent notamment l’unicité des profils, l’existence du profil actif, les URLs, les rôles d’endpoints, les limites d’exécution, les routes de logging et les contraintes wallet.

## Tests instructifs

Les tests `example_config_validates_against_schema`, `example_config_parses_and_resolves_active_profile` et `example_config_routes_global_and_operational_crate_files` démontrent le contrat complet de l’exemple actif. Les tests `parser_rejects_*` et `schema_rejects_*` documentent les invariants refusés.

## Limites

- format JSON uniquement ;
- la crate valide les références et paramètres, mais n’ouvre aucune connexion externe.