0.5.1-pre.002

ks-core/USAGE.md

@@ -0,0 +1,108 @@
+<!-- file: ks-core/USAGE.md -->
+<!-- version: 2 -->
+
+# Utilisation de ks-core
+
+## Objectif
+
+La crate expose les contrats minimaux communs utilisés par les autres crates du workspace.
+
+## Résultat partagé
+
+```rust
+fn validate_name(name: &str) -> ks_core::Result<()> {
+    if name.trim().is_empty() {
+        return std::result::Result::Err(ks_core::Error::new(
+            "name_empty",
+            "name must not be empty",
+        ));
+    }
+
+    return std::result::Result::Ok(());
+}
+```
+
+## Erreur personnalisée stable
+
+```rust
+let error = ks_core::Error::new(
+    "profile_missing",
+    "the requested profile does not exist",
+);
+
+assert_eq!(error.code(), "profile_missing");
+assert_eq!(
+    error.message(),
+    "the requested profile does not exist"
+);
+```
+
+`Error::new` doit recevoir un code stable destiné aux logs, aux tests et aux adaptateurs UI.
+
+## Familles d’erreur
+
+```rust
+let config_error = ks_core::Error::config("missing active profile");
+let io_error = ks_core::Error::io("cannot read configuration file");
+let db_error = ks_core::Error::db("database connection refused");
+
+assert_eq!(config_error.code(), "config");
+assert_eq!(io_error.code(), "io");
+assert_eq!(db_error.code(), "db");
+```
+
+Les constructeurs publics disponibles couvrent notamment la configuration, les I/O, JSON, tracing, Tauri, HTTP, WebSocket, base de données, état invalide, absence de connexion et fonctionnalité non implémentée.
+
+## Conversion depuis une erreur I/O
+
+```rust
+let read_result = std::fs::read_to_string("missing.file");
+
+let core_result: ks_core::Result<std::string::String> =
+    match read_result {
+        std::result::Result::Ok(value) => {
+            std::result::Result::Ok(value)
+        },
+        std::result::Result::Err(error) => {
+            std::result::Result::Err(ks_core::Error::from(error))
+        },
+    };
+```
+
+## Identité d’un module
+
+```rust
+let name = ks_core::ModuleName(
+    "spl_token_decoder".to_string(),
+);
+let version = ks_core::ModuleVersion(
+    "0.4.6".to_string(),
+);
+let kind = ks_core::ModuleKind::Decoder;
+
+assert_eq!(name.0, "spl_token_decoder");
+assert_eq!(version.0, "0.4.6");
+assert_eq!(kind, ks_core::ModuleKind::Decoder);
+```
+
+`ModuleKind` distingue actuellement les ingestors, extractors, observers, decoders, materializers, aggregators et validators.
+
+## Erreurs et invariants
+
+- le code d’une erreur doit rester stable ;
+- le message peut être détaillé pour l’opérateur, mais ne doit pas contenir de secret ;
+- `ModuleName` et `ModuleVersion` sont des identités, pas des mécanismes de résolution dynamique ;
+- une nouvelle variante publique doit rester compatible avec les consommateurs du workspace.
+
+## Tests de référence
+
+- `custom_error_preserves_code_and_message` ;
+- `family_error_formats_with_family_prefix`.
+
+Ces tests illustrent le contrat stable entre code, message et représentation textuelle.
+
+## Limites durables
+
+- `ks-core` ne remplace pas les types métier spécialisés ;
+- elle ne fournit pas de journalisation ni de sérialisation automatique des erreurs ;
+- elle ne contient pas de logique de transport, stockage ou protocole.