348 lines
9.0 KiB
Markdown
348 lines
9.0 KiB
Markdown
<!-- file: deltas/0.1.3/pre.007.md -->
|
|
<!-- version: 1 -->
|
|
|
|
# Delta 0.1.3-pre.007
|
|
|
|
## Base requise
|
|
|
|
Livraison précédente validée :
|
|
|
|
```text
|
|
0.1.3-pre.006
|
|
```
|
|
|
|
Version technique de cette base :
|
|
|
|
```text
|
|
workspace.package.version = "0.1.3-pre.6"
|
|
Cargo.toml header version = 47
|
|
```
|
|
|
|
Validations utilisateur exécutées le 2026-08-15 :
|
|
|
|
```text
|
|
cargo fmt --all OK
|
|
cargo check --workspace OK
|
|
cargo clippy --workspace --all-targets OK
|
|
cargo test --workspace OK
|
|
cargo tree -p ksp-logging-lib OK
|
|
cargo tree -p ksp-logging-lib -d OK — aucune duplication
|
|
cargo tree -p ksp-logging-lib -e features OK
|
|
```
|
|
|
|
Les tranches Logging préalables au premier schema Config sont donc closes.
|
|
|
|
## Objet de pre.007
|
|
|
|
Introduire la première surface JSON/JSON Schema réelle de `ksp-config-lib` sans ouvrir encore la résolution de profils, les composites ou l'environnement :
|
|
|
|
```text
|
|
registry file_id
|
|
-> resolved Config path
|
|
-> JSON parse
|
|
-> registered schema file_id
|
|
-> schema parse + meta-schema validation
|
|
-> document validation
|
|
-> bounded document semantics
|
|
```
|
|
|
|
Le premier document concret est :
|
|
|
|
```text
|
|
cfg.std.logging -> config/std.logging.json
|
|
```
|
|
|
|
validé par :
|
|
|
|
```text
|
|
schema.std.logging -> config/schemas/std.logging.schema.json
|
|
```
|
|
|
|
## Dépendances
|
|
|
|
Versions vérifiées au moment de l'ajout depuis les sources officielles `crates.io` / `docs.rs` :
|
|
|
|
```text
|
|
serde 1.0.229 -> workspace constraint ^1.0
|
|
serde_json 1.0.151 -> workspace constraint ^1.0
|
|
jsonschema 0.49.9 -> workspace constraint ^0.49
|
|
```
|
|
|
|
`jsonschema` est déclaré avec :
|
|
|
|
```text
|
|
default-features = false
|
|
```
|
|
|
|
La première surface KSP utilise un schema autonome avec références JSON Pointer internes uniquement ; aucune récupération HTTP/file de schemas distants n'est nécessaire.
|
|
|
|
Les trois dépendances sont déclarées uniquement sous `[workspace.dependencies]`, puis consommées par `ksp-config-lib` avec `.workspace = true`.
|
|
|
|
## Association document -> schema
|
|
|
|
`ConfigFileDescriptor` possède maintenant :
|
|
|
|
```text
|
|
schema_file_id: Option<ConfigFileId>
|
|
```
|
|
|
|
Le mapping par défaut devient conceptuellement :
|
|
|
|
```text
|
|
cfg.std.logging
|
|
kind = Config
|
|
filename = std.logging.json
|
|
schema_file_id = schema.std.logging
|
|
|
|
schema.std.logging
|
|
kind = Schema
|
|
filename = std.logging.schema.json
|
|
schema_file_id = none
|
|
```
|
|
|
|
Le registre valide :
|
|
|
|
- qu'un schema référencé utilise le namespace `schema.*` ;
|
|
- que son descriptor existe réellement ;
|
|
- qu'il possède `ConfigFileKind::Schema` ;
|
|
- qu'un descriptor Schema ne référence pas lui-même un schema Config.
|
|
|
|
Un `--filemap` change uniquement le filename physique et conserve cette association logique.
|
|
|
|
Aucun `schema.composite` n'est encore créé : il sera ajouté avec la tranche composite qui en a réellement besoin.
|
|
|
|
## Moteur JSON générique
|
|
|
|
Nouvelle façade :
|
|
|
|
```text
|
|
ConfigDocumentEngine
|
|
ConfigJsonDocument
|
|
```
|
|
|
|
`ConfigDocumentEngine::load_validated_document(file_id)` :
|
|
|
|
1. vérifie que le `file_id` désigne un document Config ;
|
|
2. résout son path via `ConfigBootstrapOptions` + `ConfigFileRegistry` ;
|
|
3. lit et parse le JSON ;
|
|
4. charge le schema associé par son propre `file_id` ;
|
|
5. valide le schema contre son meta-schema ;
|
|
6. valide le document contre le schema Draft 2020-12 ;
|
|
7. exécute les invariants sémantiques actuellement connus pour ce type de document ;
|
|
8. retourne le JSON validé sans transférer aux consumers la responsabilité de lecture/validation filesystem.
|
|
|
|
`ConfigJsonDocument` expose uniquement :
|
|
|
|
```text
|
|
file_id
|
|
resolved path
|
|
validated serde_json::Value
|
|
```
|
|
|
|
Les autres crates restent interdites de lecture directe des fichiers Config.
|
|
|
|
## Diagnostics
|
|
|
|
Les nouveaux codes Config distinguent :
|
|
|
|
```text
|
|
config.json_file_read_failed
|
|
config.json_syntax_invalid
|
|
config.schema_invalid
|
|
config.schema_validation_failed
|
|
config.document_semantic_invalid
|
|
```
|
|
|
|
Les erreurs enregistrent le `file_id` et le path concernés, mais jamais le contenu JSON complet.
|
|
|
|
## Premier schema Logging
|
|
|
|
`config/schemas/std.logging.schema.json` utilise JSON Schema Draft 2020-12 et couvre la surface Logging stabilisée en `pre.004/.005/.006` :
|
|
|
|
```text
|
|
format_version
|
|
logs_directory
|
|
default_profile
|
|
profiles[]
|
|
profile_id
|
|
default_filter
|
|
span_events
|
|
console
|
|
enabled
|
|
output
|
|
ansi
|
|
format
|
|
filter.level
|
|
filter.targets[]
|
|
filter.domains[]
|
|
files[]
|
|
output_id
|
|
enabled
|
|
path
|
|
rotation
|
|
format
|
|
ansi = false
|
|
filter.level
|
|
filter.targets[]
|
|
filter.domains[]
|
|
target_filters[]
|
|
```
|
|
|
|
Le schema encode notamment :
|
|
|
|
- niveaux `off/error/warn/info/debug/trace` ;
|
|
- lifecycle `off/new_and_close/full` ;
|
|
- formats `human/compact/pretty/json` ;
|
|
- rotation `never/hourly/daily` ;
|
|
- console `stdout/stderr` ;
|
|
- targets KSP ou wildcard `*` ;
|
|
- selectors uniques, wildcard utilisé seul ;
|
|
- ANSI interdit pour les fichiers ;
|
|
- ANSI + JSON console interdit.
|
|
|
|
## Document runtime et exemple
|
|
|
|
Ajouts :
|
|
|
|
```text
|
|
config/std.logging.json
|
|
config/schemas/std.logging.schema.json
|
|
config/examples/std.logging.example.json
|
|
```
|
|
|
|
Le runtime utilise déjà :
|
|
|
|
```text
|
|
"logs_directory": "${KSP_LOGS_DIRECTORY:-logs}"
|
|
```
|
|
|
|
mais `pre.007` ne résout encore aucune variable. Le placeholder reste une valeur source string valide jusqu'au resolver de `pre.010`.
|
|
|
|
Le runtime démontre :
|
|
|
|
- console configurable ;
|
|
- plusieurs fichiers ;
|
|
- formats humain et JSON ;
|
|
- filtres par level/target/domain ;
|
|
- target overrides globaux ;
|
|
- `output_id` distinct du `file_id` Config.
|
|
|
|
## Validation sémantique de base
|
|
|
|
Après JSON Schema, Config vérifie déjà les invariants directement liés à la surface Logging :
|
|
|
|
- `format_version = 1` ;
|
|
- chaînes globales requises non vides ;
|
|
- `output_id` fichier conforme ;
|
|
- `output_id` uniques dans un même profil ;
|
|
- path fichier relatif à `logs_directory`, sans traversal ;
|
|
- ANSI fichier interdit ;
|
|
- ANSI + JSON console interdit ;
|
|
- selectors non vides/uniques ;
|
|
- wildcard seul ;
|
|
- target selector et global `target_prefix` limités aux targets `ksp-*`.
|
|
|
|
Ne sont volontairement **pas encore** traités dans cette tranche :
|
|
|
|
- unicité des `profile_id` ;
|
|
- résolution de `default_profile` ;
|
|
- sélection explicite d'un profil ;
|
|
- construction d'une configuration effective globals + profil.
|
|
|
|
Ces responsabilités appartiennent à `pre.008`.
|
|
|
|
## Tests ajoutés
|
|
|
|
Les tests unitaires Config couvrent :
|
|
|
|
- document Logging runtime commité valide ;
|
|
- fichier Config absent ;
|
|
- syntaxe JSON invalide ;
|
|
- schema lui-même invalide ;
|
|
- document ne satisfaisant pas son schema ;
|
|
- document schema-valide mais sémantiquement invalide ;
|
|
- association document -> schema présente dans le registre ;
|
|
- association vers schema absent refusée.
|
|
|
|
Le test d'API publique vérifie que `ConfigDocumentEngine` charge le vrai `std.logging.json` depuis les racines Config du workspace.
|
|
|
|
## Hors scope
|
|
|
|
Cette tranche ne fait pas encore :
|
|
|
|
- résolution globals/profils/`default_profile` ;
|
|
- composite ;
|
|
- `.env` ;
|
|
- `std::env` ;
|
|
- interpolation `${...}` ;
|
|
- classification secret/public/internal ;
|
|
- redaction ;
|
|
- adaptation vers `ksp_logging_lib::LoggingSettings` ;
|
|
- mutation/persistence.
|
|
|
|
`ksp-config-lib` ne dépend donc toujours pas de `ksp-logging-lib` dans `pre.007`.
|
|
|
|
## Version technique
|
|
|
|
La prerelease devient :
|
|
|
|
```text
|
|
workspace.package.version = "0.1.3-pre.7"
|
|
Cargo.toml header version = 48
|
|
```
|
|
|
|
## Fichiers ajoutés
|
|
|
|
```text
|
|
config/std.logging.json
|
|
config/schemas/std.logging.schema.json
|
|
config/examples/std.logging.example.json
|
|
crates/ksp-config-lib/src/document.rs
|
|
crates/ksp-config-lib/unit_tests/document.rs
|
|
deltas/0.1.3/pre.007.md
|
|
```
|
|
|
|
## Fichiers modifiés
|
|
|
|
```text
|
|
Cargo.toml
|
|
crates/ksp-config-lib/Cargo.toml
|
|
crates/ksp-config-lib/src/error.rs
|
|
crates/ksp-config-lib/src/lib.rs
|
|
crates/ksp-config-lib/src/registry.rs
|
|
crates/ksp-config-lib/tests/public_api.rs
|
|
crates/ksp-config-lib/unit_tests/registry.rs
|
|
docs/plans/000-README.md
|
|
docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md
|
|
docs/plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md
|
|
docs/rules/FILE_CONTRACTS.md
|
|
```
|
|
|
|
## Contrôles exécutés dans l'environnement de génération
|
|
|
|
Les fichiers JSON ont été parsés avec `python -m json.tool`.
|
|
|
|
Le schema Draft 2020-12 et le document runtime ont également été validés avec l'implémentation Python `jsonschema` disponible dans l'environnement de génération.
|
|
|
|
Aucune commande Cargo n'est disponible dans cet environnement ; aucune validation Rust n'est donc déclarée réussie ici.
|
|
|
|
## Validations utilisateur à exécuter
|
|
|
|
```bash
|
|
cargo fmt --all
|
|
cargo check --workspace
|
|
cargo clippy --workspace --all-targets
|
|
cargo test --workspace
|
|
cargo tree -p ksp-config-lib
|
|
cargo tree -p ksp-config-lib -d
|
|
cargo tree -p ksp-config-lib -e features
|
|
```
|
|
|
|
Une attention particulière doit être portée au graphe `jsonschema` avec `default-features = false` afin de confirmer qu'aucun stack HTTP/TLS de résolution distante n'est introduit inutilement.
|
|
|
|
Après validation de `pre.007`, la prochaine tranche est :
|
|
|
|
```text
|
|
0.1.3-pre.008 — globals + profils + default_profile
|
|
```
|