v0.1.3-pre.010
This commit is contained in:
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/005-DEPENDENCY_GRAPH.md -->
|
||||
<!-- version: 8 -->
|
||||
<!-- version: 9 -->
|
||||
|
||||
# Graphe de dépendances KSP
|
||||
|
||||
@@ -76,7 +76,7 @@ ksp-core-lib
|
||||
|
||||
ksp-logging-lib -> ksp-core-lib
|
||||
ksp-config-lib -> ksp-core-lib
|
||||
ksp-config-lib -> ksp-logging-lib # lorsque du runtime logging est nécessaire
|
||||
ksp-config-lib -> ksp-logging-lib # warnings/diagnostics Config runtime
|
||||
ksp-interface-lib -> ksp-core-lib
|
||||
ksp-interface-lib -> ksp-logging-lib # lorsque du runtime logging est nécessaire
|
||||
```
|
||||
@@ -85,7 +85,7 @@ ksp-interface-lib -> ksp-logging-lib # lorsque du runtime logging est né
|
||||
|
||||
`ksp-interface-lib` est propriétaire de la façade wire et peut dépendre des crates externes Solana/interface explicitement autorisées par `RULES_DEPENDENCIES.md`.
|
||||
|
||||
`ksp-logging-lib` est la façade logging/tracing KSP et peut dépendre de `ksp-core-lib` pour `Error` / `Result`. `ksp-core-lib` n'a pas de dépendance inverse vers le logging. Les composants comportant du runtime peuvent dépendre directement de `ksp-logging-lib`; cette permission n'oblige pas les crates purement déclaratives à le faire.
|
||||
`ksp-logging-lib` est la façade logging/tracing KSP et peut dépendre de `ksp-core-lib` pour `Error` / `Result`. `ksp-core-lib` n'a pas de dépendance inverse vers le logging. Les composants comportant du runtime peuvent dépendre directement de `ksp-logging-lib`; cette permission n'oblige pas les crates purement déclaratives à le faire. Depuis `0.1.3-pre.010`, `ksp-config-lib` utilise cette dépendance pour ses warnings/diagnostics runtime, sans dépendance inverse Logging -> Config.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/plans/000-README.md -->
|
||||
<!-- version: 16 -->
|
||||
<!-- version: 17 -->
|
||||
|
||||
# Plans KSP
|
||||
|
||||
@@ -13,7 +13,7 @@ Un plan décrit le périmètre, les décisions déjà acquises, les questions ou
|
||||
- [`002-FUNCTIONAL_RELEASE_SEQUENCE.md`](002-FUNCTIONAL_RELEASE_SEQUENCE.md) — séquence active de référence des premières releases fonctionnelles ;
|
||||
- [`003-V0_1_1_CORE_FOUNDATION_PLAN.md`](003-V0_1_1_CORE_FOUNDATION_PLAN.md) — plan historique clôturé de la release stable `0.1.1`, établi par `0.1.1-pre.001` puis consolidé jusqu'à `0.1.1-rel.001`.
|
||||
- [`004-V0_1_2_LOGGING_FOUNDATION_PLAN.md`](004-V0_1_2_LOGGING_FOUNDATION_PLAN.md) — plan historique clôturé de la release stable `0.1.2`, établi par `0.1.2-pre.001` puis consolidé jusqu'à `0.1.2-rel.001`.
|
||||
- [`005-V0_1_3_CONFIG_FOUNDATION_PLAN.md`](005-V0_1_3_CONFIG_FOUNDATION_PLAN.md) — plan actif de `0.1.3 — Configuration foundation`, établi par `0.1.3-pre.001`, corrigé par `pre.001-fix.001`, complété par `pre.001-fix.002` pour le registre `file_id`/bootstrap/non-régression Logging, regranularisé par `pre.001-fix.003`, puis rescindé pendant `pre.005`; `pre.006` a fermé le routing structuré `domain`, `pre.007` le moteur JSON/JSON Schema et le premier `std.logging.json`, `pre.008` la résolution globals/profils/`default_profile`, puis `pre.009` les compositions génériques par `file_id`; `pre.010` poursuivra avec `.env`, process env et le resolver `${...}`.
|
||||
- [`005-V0_1_3_CONFIG_FOUNDATION_PLAN.md`](005-V0_1_3_CONFIG_FOUNDATION_PLAN.md) — plan actif de `0.1.3 — Configuration foundation`, établi par `0.1.3-pre.001`, corrigé par `pre.001-fix.001`, complété par `pre.001-fix.002` pour le registre `file_id`/bootstrap/non-régression Logging, regranularisé par `pre.001-fix.003`, puis rescindé pendant `pre.005`; `pre.006` a fermé le routing structuré `domain`, `pre.007` le moteur JSON/JSON Schema et le premier `std.logging.json`, `pre.008` la résolution globals/profils/`default_profile`, puis `pre.009` les compositions génériques par `file_id`; `pre.010` a livré `.env`, process env, `.env.example` et le resolver `${...}`; `pre.011` poursuivra avec sensibilité, valeur réelle/sûre et provenance.
|
||||
|
||||
Le `pre.001` de chaque release fonctionnelle peut introduire son propre plan détaillé lorsque la release s'ouvre.
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md -->
|
||||
<!-- version: 14 -->
|
||||
<!-- version: 15 -->
|
||||
|
||||
# Séquence des releases fonctionnelles KSP
|
||||
|
||||
@@ -219,7 +219,7 @@ pre.015 clôture
|
||||
|
||||
Cette prévision n'est pas un plafond : chaque prerelease doit rester une petite tranche, avec scission explicite si l'objectif dépasse environ 15–20 minutes de travail effectif.
|
||||
|
||||
`pre.006` a fermé le routing Logging structuré `domain`; `pre.007` a livré le moteur JSON/JSON Schema et `std.logging.json`; `pre.008` a ajouté la résolution générique globals/profils/`default_profile`; `pre.009` ajoute les compositions génériques par `file_id`, avec `schema.composite` mais sans composite runtime fictif. Après validation utilisateur, `pre.010` introduira `.env`, process env et le resolver `${...}`.
|
||||
`pre.006` a fermé le routing Logging structuré `domain`; `pre.007` a livré le moteur JSON/JSON Schema et `std.logging.json`; `pre.008` a ajouté la résolution générique globals/profils/`default_profile`; `pre.009` a ajouté les compositions génériques par `file_id`, avec `schema.composite` mais sans composite runtime fictif; `pre.010` ajoute le snapshot process + `.env`, `.env.example` et le resolver `${...}`. Après validation utilisateur, `pre.011` ajoutera sensibilité, valeur réelle/sûre et provenance enrichie.
|
||||
|
||||
## `0.1.4` — Config desktop par défaut
|
||||
|
||||
|
||||
@@ -1,11 +1,11 @@
|
||||
<!-- file: docs/plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md -->
|
||||
<!-- version: 12 -->
|
||||
<!-- version: 13 -->
|
||||
|
||||
# Plan `0.1.3` — Configuration foundation
|
||||
|
||||
## 1. Statut et objectif
|
||||
|
||||
Ce plan a été établi par `0.1.3-pre.001`, corrigé par `0.1.3-pre.001-fix.001/.002/.003`, puis exécuté par petites tranches. `pre.002` a livré le bootstrap Config, `pre.003` le registre `file_id`, `pre.004` les contrats publics multi-output de Logging, `pre.005` le runtime multi-sink sur niveau/target/formats, `pre.006` le routing structuré `domain`, `pre.007` le moteur JSON/JSON Schema, `pre.008` la résolution des globals/profils/`default_profile` et `pre.009` les compositions génériques par `file_id`. La prochaine tranche est `pre.010` pour `.env`, process env et le resolver `${...}`.
|
||||
Ce plan a été établi par `0.1.3-pre.001`, corrigé par `0.1.3-pre.001-fix.001/.002/.003`, puis exécuté par petites tranches. `pre.002` a livré le bootstrap Config, `pre.003` le registre `file_id`, `pre.004` les contrats publics multi-output de Logging, `pre.005` le runtime multi-sink sur niveau/target/formats, `pre.006` le routing structuré `domain`, `pre.007` le moteur JSON/JSON Schema, `pre.008` la résolution des globals/profils/`default_profile`, `pre.009` les compositions génériques par `file_id` et `pre.010` le snapshot process + `.env` et le resolver `${...}`. La prochaine tranche est `pre.011` pour sensibilité, valeur réelle/sûre et provenance enrichie.
|
||||
|
||||
La base auditée reste la release stable `v0.1.2`.
|
||||
|
||||
@@ -163,6 +163,7 @@ KSP conserve :
|
||||
- composition propre à un exécutable/application ;
|
||||
- sélection d'un profil spécialisé depuis la composition ;
|
||||
- `.env` séparé des documents JSON ;
|
||||
- `.env.example` versionné et maintenu au fil de l'apparition des variables runtime ;
|
||||
- priorité de l'environnement réel du processus sur `.env` ;
|
||||
- fallback déclaré au point d'usage via `${NAME:-fallback}` ;
|
||||
- classification nominale des variables ;
|
||||
@@ -1779,16 +1780,27 @@ Tranche livrée :
|
||||
- `ConfigDocumentEngine::load_resolved_composite(file_id, requested_profile)` est prêt pour les futurs descriptors `cfg.composite.<consumer>` ;
|
||||
- les tests utilisent un descriptor composite privé à la crate pointant vers l’exemple versionné afin de valider la résolution complète sans créer un composite runtime fictif.
|
||||
|
||||
La validation utilisateur de `pre.009-fix.001` est acquise : `fmt/check/clippy/test` passent, les 39 tests unitaires Config et 7 tests publics passent, et le graphe de dépendances reste conforme avec le seul doublon transitif `syn 2`/`syn 3` déjà connu via `jsonschema`.
|
||||
|
||||
### `0.1.3-pre.010` — `.env` + process env + resolver `${...}`
|
||||
|
||||
- lecture process env ;
|
||||
- lecture `.env` sans écrasement process ;
|
||||
- priorité process > `.env` > fallback ;
|
||||
- `${NAME}` / `${NAME:-fallback}` ;
|
||||
- fallback appliqué seulement si la variable est absente ;
|
||||
- missing diagnostics + warning ;
|
||||
- namespaces KSP/KSPB ;
|
||||
- tests d'isolation process env.
|
||||
Tranche livrée :
|
||||
|
||||
- `ConfigEnvironment::load()` capture les variables KSP/KSPB du processus puis lit `./.env` sans modifier l'environnement externe ;
|
||||
- l'absence de `.env` est valide et équivaut à une source locale vide ; les autres erreurs de lecture sont distinctes ;
|
||||
- priorité effective process > `.env` > fallback, y compris le cas d'une chaîne vide explicitement définie ;
|
||||
- `ConfigEnvironmentValue` expose la valeur réelle et sa source `Process` / `DotEnv` / `Fallback` sans implémentation `Debug` afin de ne pas créer une fuite accidentelle avant le contrat de redaction de `pre.011` ;
|
||||
- `${NAME}` et `${NAME:-fallback}` sont résolus dans les strings, maps et valeurs JSON récursives ; plusieurs placeholders sont supportés ;
|
||||
- le fallback reste littéral et n'est pas récursivement interprété dans cette tranche ;
|
||||
- une variable manquante sans fallback retourne `config.environment_variable_missing` et émet un warning via `ksp-logging-lib` avec target `ksp-config-lib`, sans valeur dans le diagnostic ;
|
||||
- seuls les namespaces `KSP_*` et `KSPB_*` sont acceptés par l'API Config ;
|
||||
- le parser `.env` supporte commentaires, `export`, valeurs non quotées/simplement/doublement quotées et refuse les doublons KSP ambigus ;
|
||||
- les tests de priorité process utilisent des sources injectées/itérateurs synthétiques : ils ne mutent jamais le vrai environnement du processus, ce qui évite `unsafe` en Rust 2024 ;
|
||||
- `ResolvedConfigProfile::resolve_effective_environment()` résout la vue effective sans modifier le profil source ni sa provenance Global/Profile ;
|
||||
- `ksp-config-lib` dépend désormais réellement de `ksp-logging-lib` pour ses warnings Config ; la dépendance inverse reste interdite ;
|
||||
- `.env.example` est créé à la racine avec `KSP_LOGS_DIRECTORY`, seule variable runtime actuellement utilisée ;
|
||||
- la règle durable impose désormais d'ajouter toute nouvelle variable runtime KSP/KSPB à `.env.example`, avec commentaire d'usage, dans le même delta que sa première utilisation ;
|
||||
- `.gitignore` possédait déjà la règle correcte `.env`, `.env.*`, `!.env.example`; aucun changement n'est nécessaire.
|
||||
|
||||
### `0.1.3-pre.011` — sensibilité + valeurs real/safe/provenance
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/rules/FILE_CONTRACTS.md -->
|
||||
<!-- version: 11 -->
|
||||
<!-- version: 12 -->
|
||||
|
||||
# Contrats des fichiers
|
||||
|
||||
@@ -9,17 +9,19 @@ Les règles `FILE-*` définissent la responsabilité et le mode de modification
|
||||
|
||||
## Fichiers racine et configuration Cargo
|
||||
|
||||
| Fichier | Responsabilité | Règle de modification |
|
||||
|----------------------|-----------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| `.gitignore` | Exclure uniquement les artefacts non versionnés décidés par le projet. | Ajouter une exclusion lorsqu'un besoin réel apparaît ; éviter les exclusions spéculatives. |
|
||||
| `README.md` | Présenter KSP, sa finalité, son périmètre général, ses principes et les points d'entrée. | Mettre à jour lorsqu'une définition structurante du projet change ; ne pas y consigner l'historique des versions. |
|
||||
| `RULES.md` | Indexer les règles normatives. | Modifier uniquement lorsque la structure normative ou ses points d'entrée changent. |
|
||||
| `Cargo.toml` | Définir le workspace, sa version Cargo, les métadonnées héritées et les lints communs. | Modifier lors de toute prerelease/release non-fix, lors d'un correctif touchant le code/build/runtime/configuration/migrations, lorsqu'une crate entre/sort du workspace ou lorsqu'un contrat Cargo commun change. Un correctif purement documentaire ou de référence non consommée par le runtime ne force pas un changement de version Cargo. |
|
||||
| `.cargo/config.toml` | Définir les réglages Cargo propres au workspace qui ne relèvent pas du manifeste, notamment l'emplacement des artefacts de build. | Modifier lorsqu'un réglage Cargo commun change ; ne pas y placer de secret ni de configuration spécifique à une machine particulière. |
|
||||
| `rustfmt.toml` | Définir le formatage Rust commun. | Modifier comme changement normatif, avec justification dans le delta. |
|
||||
| `clippy.toml` | Définir les paramètres Clippy communs. | Modifier comme changement normatif, avec justification dans le delta. |
|
||||
| `ROADMAP.md` | Décrire les objectifs globaux et les grandes étapes prévues par phase/version, avec leur état synthétique. | Modifier lorsqu'un objectif, une grande étape, un report, une annulation ou un état global change ; ne pas y recopier le détail des prereleases prévu dans les plans de version. |
|
||||
| `CHANGELOG.md` | Résumer les releases stables dans un ordre chronologique décroissant, sous forme d'un ou plusieurs paragraphes par release. | Synchroniser lors de la phase documentaire finale ; ne pas dupliquer les deltas ni créer de changelog par crate/module. |
|
||||
| Fichier | Responsabilité | Règle de modification |
|
||||
|----------------------|-----------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| `.gitignore` | Exclure uniquement les artefacts non versionnés décidés par le projet. | Ajouter une exclusion lorsqu'un besoin réel apparaît ; éviter les exclusions spéculatives. |
|
||||
| `.env` | Fournir les valeurs d'environnement locales KSP/KSPB du runtime lorsqu'elles ne viennent pas du processus externe. | Fichier local non versionné et non échangé ; lu puis, à terme, modifié uniquement par `ksp-config-lib`. L'environnement du processus garde priorité sur cette source. |
|
||||
| `.env.example` | Inventorier le contrat versionné de toutes les variables d'environnement runtime KSP/KSPB utilisées par les fichiers Config ou le code. | Ajouter la variable dans le même delta que sa première utilisation. Chaque entrée est précédée d'un commentaire décrivant son usage ; elle peut être active avec une valeur par défaut/générique non secrète ou rester commentée. Ce fichier ne contient jamais de vrai secret. |
|
||||
| `README.md` | Présenter KSP, sa finalité, son périmètre général, ses principes et les points d'entrée. | Mettre à jour lorsqu'une définition structurante du projet change ; ne pas y consigner l'historique des versions. |
|
||||
| `RULES.md` | Indexer les règles normatives. | Modifier uniquement lorsque la structure normative ou ses points d'entrée changent. |
|
||||
| `Cargo.toml` | Définir le workspace, sa version Cargo, les métadonnées héritées et les lints communs. | Modifier lors de toute prerelease/release non-fix, lors d'un correctif touchant le code/build/runtime/configuration/migrations, lorsqu'une crate entre/sort du workspace ou lorsqu'un contrat Cargo commun change. Un correctif purement documentaire ou de référence non consommée par le runtime ne force pas un changement de version Cargo. |
|
||||
| `.cargo/config.toml` | Définir les réglages Cargo propres au workspace qui ne relèvent pas du manifeste, notamment l'emplacement des artefacts de build. | Modifier lorsqu'un réglage Cargo commun change ; ne pas y placer de secret ni de configuration spécifique à une machine particulière. |
|
||||
| `rustfmt.toml` | Définir le formatage Rust commun. | Modifier comme changement normatif, avec justification dans le delta. |
|
||||
| `clippy.toml` | Définir les paramètres Clippy communs. | Modifier comme changement normatif, avec justification dans le delta. |
|
||||
| `ROADMAP.md` | Décrire les objectifs globaux et les grandes étapes prévues par phase/version, avec leur état synthétique. | Modifier lorsqu'un objectif, une grande étape, un report, une annulation ou un état global change ; ne pas y recopier le détail des prereleases prévu dans les plans de version. |
|
||||
| `CHANGELOG.md` | Résumer les releases stables dans un ordre chronologique décroissant, sous forme d'un ou plusieurs paragraphes par release. | Synchroniser lors de la phase documentaire finale ; ne pas dupliquer les deltas ni créer de changelog par crate/module. |
|
||||
|
||||
## Répertoire `docs/`
|
||||
|
||||
@@ -47,6 +49,8 @@ Les règles `FILE-*` définissent la responsabilité et le mode de modification
|
||||
|
||||
Les noms physiques sont remplaçables via le registre Config lorsque le contrat le permet ; les consumers référencent les documents par `file_id`, pas par filename.
|
||||
|
||||
Le fichier runtime d'environnement est toujours `./.env` pour `0.1.3`. Il n'est ni un document `config/` ni une source de bootstrap de `cfgpath`/`schemapath`. Le template `.env.example` est la référence versionnée permettant de créer localement `.env` et d'identifier par diff les nouvelles clés attendues.
|
||||
|
||||
Pour un document standard profilé, `default_profile` et `profiles` sont des clés structurelles réservées. Les autres propriétés top-level sont des valeurs globales. Chaque entrée de `profiles` possède un `profile_id` unique ; `default_profile` référence obligatoirement l'un de ces identifiants. La résolution Config peut sélectionner le profil par défaut ou un profil explicite et conserve séparément la provenance `Global` / `Profile` de la vue effective. Les consumers ne reconstituent jamais eux-mêmes cette fusion.
|
||||
|
||||
## Répertoire `prompts/`
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/rules/RULES_KSP.md -->
|
||||
<!-- version: 14 -->
|
||||
<!-- version: 15 -->
|
||||
|
||||
# Règles spécifiques à KSP
|
||||
|
||||
@@ -26,6 +26,17 @@
|
||||
- **KSP-API-006** — `ksp-store-lib` contient PostgreSQL comme implémentation officielle de référence derrière `ksp-store-api`.
|
||||
- **KSP-API-007** — Une crate `*-api` n'est créée que lorsqu'un vrai besoin d'extension, backend ou lifecycle le justifie ; la symétrie de nommage n'est jamais une justification suffisante.
|
||||
|
||||
|
||||
## Configuration et environnement
|
||||
|
||||
- **KSP-CONFIG-001** — `ksp-config-lib` est l'unique propriétaire KSP de la lecture des documents Config, du `.env`, des variables applicatives `KSP_*` / `KSPB_*` et de leur résolution ; les autres crates ne lisent pas directement ces sources.
|
||||
- **KSP-CONFIG-002** — Les namespaces d'environnement sont `KSP_*`, `KSP_PUBLIC_*`, `KSP_SECRET_*` pour les composants génériques et `KSPB_*`, `KSPB_PUBLIC_*`, `KSPB_SECRET_*` pour la branche bot ; les anciens préfixes KS/KB ne sont pas utilisés dans KSP.
|
||||
- **KSP-CONFIG-003** — La priorité d'une variable est environnement du processus > `./.env` > fallback déclaré au point d'usage. Une chaîne vide explicitement définie est une valeur présente et n'active pas le fallback.
|
||||
- **KSP-CONFIG-004** — Le `.env` runtime est local, non versionné et non échangé. Config le lit sans prétendre modifier l'environnement du shell/systemd/parent qui a lancé le processus.
|
||||
- **KSP-CONFIG-005** — `.env.example` est versionné à la racine et inventorie toutes les variables d'environnement runtime KSP/KSPB utilisées par les fichiers Config ou le code ; toute nouvelle variable y est ajoutée dans le même delta que sa première utilisation.
|
||||
- **KSP-CONFIG-006** — Chaque entrée de `.env.example` est précédée d'un commentaire décrivant son usage/utilité. Sa valeur peut être un défaut sûr, une valeur générique non secrète ou une entrée commentée ; aucun vrai secret n'y est enregistré.
|
||||
- **KSP-CONFIG-007** — Les placeholders Config utilisent `${NAME}` ou `${NAME:-fallback}`. Le fallback s'applique uniquement si la variable est absente ; l'interpolation appartient à `ksp-config-lib` et non aux consumers.
|
||||
|
||||
## Programmes et exécution
|
||||
|
||||
- **KSP-PROGRAM-001** — Les contrats de décodage et de préparation d'exécution appartiennent à `ksp-program-api`; les implémentations officielles intégrées appartiennent à `ksp-program-lib`.
|
||||
|
||||
Reference in New Issue
Block a user