v0.1.0-pre.069

2026-07-31 13:25:26 +02:00
parent f23ecd6675
commit 46071b7fed
21 changed files with 799 additions and 410 deletions
--- a/kb-logging/CHANGELOG.md
+++ b/kb-logging/CHANGELOG.md
@@ -0,0 +1,40 @@
+<!-- file: kb-logging/CHANGELOG.md -->
+<!-- version: 2 -->
+
+# CHANGELOG — kb-logging
+
+## 0.1.0-pre.069-fix-001
+
+### Corrigé
+
+- suppression de la section `Non publié`, incompatible avec le rôle chronologique du changelog ;
+- retrait des travaux futurs du changelog.
+
+### Documentation
+
+- réécriture de `TODO.md` sous forme de tâches uniquement ;
+- correction de `USAGE.md` pour ne conserver que les contraintes runtime durables.
+
+## 0.1.0-pre.069
+
+### Documentation
+
+- création de `TODO.md`, `USAGE.md` et du changelog détaillé ;
+- réécriture du README selon la séparation bot3 entre configuration et runtime logging.
+
+## 0.1.0
+
+### Migré
+
+- migration du runtime de logging et tracing depuis bot2 ;
+- consolidation des routes console/fichier, formats, rotations et filtres de targets.
+
+### Modifié
+
+- adoption des règles Rust 2024 et Khadhroony ;
+- erreurs structurées via `kb_core::Error` ;
+- conservation explicite des guards non bloquants.
+
+### Validation
+
+- tests des routes, formats, niveaux, wildcards, writers et targets canoniques du workspace.
--- a/kb-logging/README.md
+++ b/kb-logging/README.md
@@ -1,38 +1,38 @@
 <!-- file: kb-logging/README.md -->
-<!-- version: 5 -->
+<!-- version: 3 -->

 # kb-logging

-`kb-logging` initialise le routage `tracing` commun du workspace.
+`kb-logging` initialise le subscriber global `tracing` à partir d’une configuration de routes explicites vers la console ou des fichiers.

-## Responsabilité
+## Responsabilités

-Le crate transforme la configuration du profil actif en layers `tracing_subscriber` et route les événements vers la console, les fichiers humains et les fichiers JSONL. Le `LoggingGuard` retourné par `init_logging` doit rester vivant pendant toute la durée du processus afin de conserver les writers non bloquants.
+- sélectionner les routes activées ;
+- appliquer niveaux, targets exactes et préfixes wildcard ;
+- créer les writers non bloquants ;
+- gérer les formats human, compact, pretty et JSON ;
+- gérer les rotations de fichiers supportées ;
+- conserver les `WorkerGuard` pendant toute la durée du processus.

-Les décisions de niveau et de target sont appliquées par chaque writer de route, avec un seul filtre d’admission agrégé en amont. Elles ne créent pas un `Filtered` layer par sortie : `tracing-subscriber` réserve seulement 64 identifiants de filtres par subscriber, tandis que la matrice complète comporte désormais plus de 64 routes activables. Le filtrage writer conserve les niveaux, targets exacts, préfixes et overrides configurés sans imposer cette limite au nombre de sorties ; le filtre agrégé évite de formater un événement qu’aucune route n’accepte.
+## Hors périmètre

-Les chemins relatifs sont résolus depuis la racine du workspace. L’ANSI est désactivé dans les formatters fichier et retiré une seconde fois par `StripAnsiMakeWriter` afin de nettoyer les messages provenant d’une WebView ou d’une dépendance externe.
+La crate ne charge pas le fichier de configuration et ne définit pas les targets des autres crates. `kb-config` fournit les valeurs et chaque crate publie son propre target canonique.

-## Contrat de targets
+## API publique

-`kb-logging` utilise le target canonique `kb-logging`, défini dans `src/constants.rs`. Chaque crate qui dépend de `tracing` doit suivre le même contrat avec son propre nom Cargo.
+- `init_logging` initialise le subscriber global ;
+- `LoggingConfig`, `LogTargetConfig` et `LogTargetFilterConfig` décrivent les routes ;
+- `LoggingGuard` maintient les writers et expose les routes installées ;
+- `tracing_target` retourne le target canonique de la crate ;
+- `LogFileRoute` reste disponible pour les anciens appelants file-only.

-Le test `every_tracing_crate_has_one_canonical_target_constant` inspecte les manifests du workspace et vérifie qu’une crate déclarant `tracing.workspace = true` possède exactement une constante conforme.
+## Statut

-## Matrice de fichiers
+L’initialisation multi-routes est fonctionnelle. Elle échoue explicitement si aucune route n’est activée ou si le subscriber global a déjà été initialisé.

-Chaque profil actif configure :
+## Documents

-```text
-logs/<profile>/debug.log
-logs/<profile>/info.log
-logs/<profile>/error.jsonl
-logs/<profile>/app.log
-logs/<profile>/<crate>/debug.log
-logs/<profile>/<crate>/info.log
-logs/<profile>/<crate>/error.jsonl
-```
-
-Les fichiers sont en rotation quotidienne. Les routes `debug` et `info` sont cumulatives ; les routes `error.jsonl` sont forcées au niveau `error` et n’ajoutent pas les overrides verbeux des dépendances.
-
-Le contrat détaillé se trouve dans `docs/LOGGING.md` et `docs/TRACING_CONTRACT.md`.
+- [Utilisation](USAGE.md)
+- [Travaux restants](TODO.md)
+- [Historique](CHANGELOG.md)
+- [Guide de configuration](../kb-config/USAGE.md)
--- a/kb-logging/TODO.md
+++ b/kb-logging/TODO.md
@@ -0,0 +1,11 @@
+<!-- file: kb-logging/TODO.md -->
+<!-- version: 2 -->
+
+# TODO — kb-logging
+
+## Série 0.5.x — configuration logging dédiée
+
+- [ ] définir avec `kb-config` le contrat de la future configuration logging séparée ;
+- [ ] préserver la compatibilité des targets, niveaux, filtres, formats et routes pendant la migration ;
+- [ ] ajouter les tests de migration du format de configuration ;
+- [ ] mettre à jour les exemples et la documentation après implémentation du nouveau chargement.
--- a/kb-logging/USAGE.md
+++ b/kb-logging/USAGE.md
@@ -0,0 +1,67 @@
+<!-- file: kb-logging/USAGE.md -->
+<!-- version: 2 -->
+
+# Utilisation de kb-logging
+
+## Initialisation
+
+```rust
+let config = kb_logging::LoggingConfig {
+    default_level: "info".to_string(),
+    targets: vec![kb_logging::LogTargetConfig {
+        name: "console".to_string(),
+        enabled: true,
+        sink: "console".to_string(),
+        level: "info".to_string(),
+        path: String::new(),
+        rotation: "none".to_string(),
+        format: "compact".to_string(),
+        ansi: true,
+        targets: vec!["kb-*".to_string()],
+    }],
+    target_filters: Vec::new(),
+};
+let guard = match kb_logging::init_logging(&config) {
+    Ok(value) => value,
+    Err(error) => return Err(error),
+};
+```
+
+`init_logging` doit être appelée une seule fois par processus. Le `LoggingGuard` retourné doit rester vivant jusqu’à l’arrêt afin de ne pas interrompre les writers non bloquants.
+
+## Inspection des routes
+
+```rust
+assert_eq!(guard.route_count(), 1);
+assert_eq!(guard.guard_count(), 1);
+assert_eq!(guard.route_names(), &["console".to_string()]);
+```
+
+## Routes fichier
+
+Pour une route `file`, `path` doit désigner le fichier cible et `rotation` doit être une valeur supportée (`none`, `never`, `daily` ou `hourly`). Les formats supportés sont `human`, `compact`, `pretty` et `json`.
+
+## Filtres de targets
+
+Les routes acceptent des targets exactes et des préfixes wildcard. Les `target_filters` ajoutent des niveaux spécifiques aux routes wildcard. Une route d’erreur conserve la sémantique stricte prévue par l’implémentation.
+
+## Erreurs
+
+Les erreurs utilisent `kb_core::Error`. Les cas principaux sont :
+
+- aucune route activée ;
+- sink, format, rotation ou niveau inconnu ;
+- chemin fichier invalide ;
+- échec d’initialisation du subscriber global.
+
+## Tests instructifs
+
+- `enabled_routes_keep_all_configured_outputs` vérifie l’installation multi-routes ;
+- `route_writer_filter_preserves_target_and_level_semantics` vérifie l’admission finale ;
+- `more_than_64_routes_compose_without_filtered_layer_ids` couvre un volume élevé de routes ;
+- `every_tracing_crate_exposes_canonical_targets` vérifie la cohérence des targets du workspace.
+
+## Limites
+
+- initialisation globale unique par processus ;
+- configuration fournie par l’appelant ;