v0.1.0-pre.069

kb-config/USAGE.md

@@ -0,0 +1,100 @@
+<!-- file: kb-config/USAGE.md -->
+<!-- version: 2 -->
+
+# 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),
+};
+```
+
+`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.
+
+## 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),
+};
+```
+
+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),
+};
+```
+
+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.
+
+## 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.