v0.1.3-pre.010
This commit is contained in:
298
deltas/0.1.3/pre.010.md
Normal file
298
deltas/0.1.3/pre.010.md
Normal file
@@ -0,0 +1,298 @@
|
||||
<!-- file: deltas/0.1.3/pre.010.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Delta 0.1.3-pre.010
|
||||
|
||||
## Base requise
|
||||
|
||||
Livraison précédente validée :
|
||||
|
||||
```text
|
||||
0.1.3-pre.009-fix.001
|
||||
```
|
||||
|
||||
Version technique de cette base :
|
||||
|
||||
```text
|
||||
workspace.package.version = "0.1.3-pre.9.fix.1"
|
||||
Cargo.toml header version = 51
|
||||
```
|
||||
|
||||
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-config-lib OK
|
||||
cargo tree -p ksp-config-lib -d OK, doublon transitif syn 2/3 déjà connu
|
||||
cargo tree -p ksp-config-lib -e features OK
|
||||
```
|
||||
|
||||
`cargo test --workspace` confirme notamment 39 tests unitaires + 7 tests publics pour `ksp-config-lib`.
|
||||
|
||||
## Objet de pre.010
|
||||
|
||||
Introduire la première résolution environnementale Config réellement consommable :
|
||||
|
||||
```text
|
||||
process environment
|
||||
>
|
||||
./.env
|
||||
>
|
||||
placeholder/API fallback
|
||||
->
|
||||
ConfigEnvironmentValue
|
||||
->
|
||||
${NAME} / ${NAME:-fallback}
|
||||
->
|
||||
JSON effective values
|
||||
```
|
||||
|
||||
La sensibilité et les représentations sûres restent volontairement réservées à `pre.011`.
|
||||
|
||||
## Propriété et sources
|
||||
|
||||
`ConfigEnvironment` est le snapshot possédé par `ksp-config-lib`.
|
||||
|
||||
`ConfigEnvironment::load()` :
|
||||
|
||||
1. capture les variables supportées héritées par le processus ;
|
||||
2. lit `./.env` s'il existe ;
|
||||
3. ne modifie jamais l'environnement du processus, du shell, de systemd ou du parent ;
|
||||
4. considère l'absence de `.env` comme une source locale vide.
|
||||
|
||||
Une erreur de lecture réelle de `.env` reste distincte de son absence.
|
||||
|
||||
Les seuls namespaces applicatifs acceptés sont :
|
||||
|
||||
```text
|
||||
KSP_*
|
||||
KSPB_*
|
||||
```
|
||||
|
||||
ce qui couvre naturellement :
|
||||
|
||||
```text
|
||||
KSP_PUBLIC_*
|
||||
KSP_SECRET_*
|
||||
KSPB_PUBLIC_*
|
||||
KSPB_SECRET_*
|
||||
```
|
||||
|
||||
## Priorité et chaîne vide
|
||||
|
||||
`ConfigEnvironment::resolve_variable(name, fallback)` applique :
|
||||
|
||||
```text
|
||||
process > .env > fallback > missing
|
||||
```
|
||||
|
||||
Une chaîne vide explicitement présente dans le processus ou `.env` reste une valeur définie. Elle ne déclenche pas le fallback.
|
||||
|
||||
`ConfigEnvironmentValue` expose :
|
||||
|
||||
```text
|
||||
variable_name
|
||||
value réelle
|
||||
source = Process | DotEnv | Fallback
|
||||
```
|
||||
|
||||
Le type n'implémente volontairement pas `Debug` afin de ne pas créer une voie de fuite accidentelle avant l'introduction de la sensibilité/redaction en `pre.011`.
|
||||
|
||||
## Resolver `${...}`
|
||||
|
||||
Config supporte :
|
||||
|
||||
```text
|
||||
${KSP_VAR}
|
||||
${KSP_VAR:-fallback}
|
||||
```
|
||||
|
||||
Règles :
|
||||
|
||||
- plusieurs placeholders peuvent apparaître dans une même string ;
|
||||
- le fallback n'est utilisé que si la variable est absente ;
|
||||
- le fallback est littéral dans cette tranche et n'est pas récursivement interprété ;
|
||||
- les placeholders imbriqués/malformés sont refusés ;
|
||||
- les clés JSON ne sont pas interpolées ; seules les valeurs string le sont ;
|
||||
- objets et tableaux JSON sont parcourus récursivement.
|
||||
|
||||
APIs principales :
|
||||
|
||||
```text
|
||||
ConfigEnvironment::resolve_variable(...)
|
||||
ConfigEnvironment::resolve_text(...)
|
||||
ConfigEnvironment::resolve_json(...)
|
||||
ConfigEnvironment::resolve_map(...)
|
||||
ResolvedConfigProfile::resolve_effective_environment(...)
|
||||
```
|
||||
|
||||
La résolution d'environnement d'un profil produit une nouvelle map effective et ne modifie pas la source, le `profile_id`, la provenance `Global/Profile` ni la sélection du profil déjà résolu.
|
||||
|
||||
## Variable manquante
|
||||
|
||||
Une référence sans valeur process, sans valeur `.env` et sans fallback retourne :
|
||||
|
||||
```text
|
||||
config.environment_variable_missing
|
||||
```
|
||||
|
||||
Config émet également un warning via la façade KSP :
|
||||
|
||||
```text
|
||||
target = ksp-config-lib
|
||||
domain = config.environment
|
||||
```
|
||||
|
||||
Le warning et l'erreur contiennent le nom de la variable mais jamais sa valeur.
|
||||
|
||||
`ksp-config-lib` dépend donc maintenant réellement de `ksp-logging-lib`. La dépendance inverse Logging -> Config reste interdite.
|
||||
|
||||
## `.env`
|
||||
|
||||
Le parser Config de cette tranche accepte un sous-ensemble déterministe adapté au fichier KSP géré :
|
||||
|
||||
- lignes vides et commentaires `#` ;
|
||||
- préfixe optionnel `export ` ;
|
||||
- `NAME=value` ;
|
||||
- valeur non quotée ;
|
||||
- valeur entre quotes simples ;
|
||||
- valeur entre quotes doubles avec escapes bornés `\\`, `\"`, `\n`, `\r`, `\t` ;
|
||||
- commentaire inline d'une valeur non quotée lorsqu'il commence par ` #` ;
|
||||
- chaîne vide ;
|
||||
- clés étrangères valides ignorées par Config ;
|
||||
- doublon d'une clé KSP/KSPB refusé pour éviter une résolution locale ambiguë.
|
||||
|
||||
Aucune interpolation interne du fichier `.env` n'est ajoutée dans cette tranche.
|
||||
|
||||
## `.env.example` — nouvelle règle durable
|
||||
|
||||
Le dépôt possède désormais à la racine :
|
||||
|
||||
```text
|
||||
.env.example
|
||||
```
|
||||
|
||||
Ce fichier est versionné et sert d'inventaire canonique des variables runtime KSP/KSPB utilisées par les fichiers Config ou le code opérationnel.
|
||||
|
||||
Règles enregistrées :
|
||||
|
||||
- toute nouvelle variable runtime KSP/KSPB est ajoutée à `.env.example` dans le même delta que sa première utilisation ;
|
||||
- chaque variable est précédée d'un commentaire expliquant son usage/utilité ;
|
||||
- une entrée peut être active avec une valeur par défaut sûre, porter une valeur générique non secrète ou être commentée ;
|
||||
- aucun vrai secret n'y est stocké ;
|
||||
- le fichier local `.env` reste non versionné et non échangé ;
|
||||
- l'objectif est de pouvoir créer `.env` depuis `.env.example` et repérer localement les nouvelles clés par diff.
|
||||
|
||||
La première entrée est :
|
||||
|
||||
```text
|
||||
KSP_LOGS_DIRECTORY=logs
|
||||
```
|
||||
|
||||
car `config/std.logging.json` est actuellement le seul fichier runtime utilisant une variable d'environnement.
|
||||
|
||||
`.gitignore` possédait déjà :
|
||||
|
||||
```text
|
||||
.env
|
||||
.env.*
|
||||
!.env.example
|
||||
```
|
||||
|
||||
et n'a donc pas besoin d'être modifié.
|
||||
|
||||
## Tests
|
||||
|
||||
Les nouveaux tests couvrent notamment :
|
||||
|
||||
- priorité process > `.env` > fallback ;
|
||||
- chaîne vide process et `.env` considérée comme définie ;
|
||||
- variable manquante sans fallback ;
|
||||
- namespaces KSP/KSPB ;
|
||||
- résolution de plusieurs placeholders ;
|
||||
- placeholder malformé/imbriqué ;
|
||||
- résolution récursive object/array JSON ;
|
||||
- parsing `.env` avec commentaires, `export` et quotes ;
|
||||
- refus des doublons KSP dans `.env` ;
|
||||
- collecte process synthétique sans mutation du vrai environnement ;
|
||||
- résolution du fallback `${KSP_LOGS_DIRECTORY:-logs}` du document Logging commité ;
|
||||
- présence commentée de `KSP_LOGS_DIRECTORY` dans `.env.example` ;
|
||||
- disponibilité de la surface environment depuis le crate-root.
|
||||
|
||||
Les tests n'appellent pas `std::env::set_var` / `remove_var`; aucune mutation unsafe de l'environnement n'est nécessaire en Rust 2024.
|
||||
|
||||
## Dépendances
|
||||
|
||||
Aucune nouvelle dépendance externe n'est ajoutée.
|
||||
|
||||
Dépendance KSP désormais utilisée :
|
||||
|
||||
```text
|
||||
ksp-config-lib -> ksp-logging-lib
|
||||
```
|
||||
|
||||
pour les warnings/diagnostics runtime Config.
|
||||
|
||||
Les dépendances externes `serde`, `serde_json` et `jsonschema` restent inchangées.
|
||||
|
||||
## Version technique
|
||||
|
||||
La prerelease devient :
|
||||
|
||||
```text
|
||||
workspace.package.version = "0.1.3-pre.10"
|
||||
Cargo.toml header version = 52
|
||||
```
|
||||
|
||||
## Fichiers ajoutés
|
||||
|
||||
```text
|
||||
.env.example
|
||||
crates/ksp-config-lib/src/environment.rs
|
||||
crates/ksp-config-lib/unit_tests/environment.rs
|
||||
deltas/0.1.3/pre.010.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/profile.rs
|
||||
crates/ksp-config-lib/tests/public_api.rs
|
||||
docs/architecture/005-DEPENDENCY_GRAPH.md
|
||||
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
|
||||
docs/rules/RULES_KSP.md
|
||||
```
|
||||
|
||||
## Fichiers supprimés
|
||||
|
||||
Aucun.
|
||||
|
||||
## Contrôles exécutés dans l'environnement de génération
|
||||
|
||||
- parsing TOML du manifest racine et de `ksp-config-lib` ;
|
||||
- audit statique des accès `std::env::*` : seul `crates/ksp-config-lib/src/environment.rs` lit l'environnement applicatif ;
|
||||
- audit statique des variables runtime exactes dans `crates/*/src` + `config/` : `KSP_LOGS_DIRECTORY` est la seule clé actuelle et elle est présente dans `.env.example` ;
|
||||
- absence de `unsafe`, `unwrap`, `expect`, `panic!` et `?` dans le nouveau code de production Config ;
|
||||
- contrôle des headers/version et des lignes Rust ajoutées/modifiées ;
|
||||
- comparaison du delta avec la base `pre.009-fix.001` ;
|
||||
- aucun `Cargo.lock` ajouté.
|
||||
|
||||
Le toolchain Rust n'est pas disponible dans l'environnement de génération. `cargo fmt/check/clippy/test` doivent donc être exécutés par l'utilisateur.
|
||||
|
||||
## Étape suivante
|
||||
|
||||
Après validation utilisateur :
|
||||
|
||||
```text
|
||||
0.1.3-pre.011 — sensibilité Public/Internal/Secret + real/safe/provenance + redaction par segment
|
||||
```
|
||||
Reference in New Issue
Block a user