124 lines
6.4 KiB
Markdown
124 lines
6.4 KiB
Markdown
<!-- file: docs/rules/400-VALIDATION.md -->
|
|
<!-- version: 4 -->
|
|
|
|
# Validation locale Knowledge
|
|
|
|
## Principe
|
|
|
|
Une tranche sélectionne ses preuves à partir du scope modifié, des contrats potentiellement invalidés et du risque réel. La validation est proportionnée : elle ne rejoue pas mécaniquement toutes les commandes disponibles lorsque celles-ci n'apportent aucune preuve nouvelle.
|
|
|
|
La matrice canonique est [`../validation/001-VALIDATION_MATRIX.md`](../validation/001-VALIDATION_MATRIX.md).
|
|
|
|
## Statuts
|
|
|
|
Les statuts reconnus sont :
|
|
|
|
```text
|
|
PASS toutes les preuves requises ont réussi
|
|
FAIL au moins une preuve requise a échoué
|
|
PARTIAL seules certaines preuves requises ont été acquises
|
|
BLOCKED un prérequis externe empêche d'exécuter une preuve requise
|
|
```
|
|
|
|
Un statut incomplet ne devient jamais implicitement `PASS`.
|
|
|
|
## Autorité de la gate
|
|
|
|
La gate opérateur exécutée dans l'environnement autoritaire possède le statut de tranche. Une prévalidation par assistant, génération locale ou CI supplémentaire peut réduire le risque de livraison mais ne remplace pas cette gate.
|
|
|
|
Une commande qui échoue dans la gate reste un `FAIL` même si des tests exécutés ensuite passent. Les preuves positives sont conservées dans le diagnostic mais ne neutralisent pas l'échec requis.
|
|
|
|
## Catégories de preuve
|
|
|
|
Les gates peuvent combiner, selon le scope :
|
|
|
|
```text
|
|
FORMAT état produit par le formatter officiel
|
|
AUDIT contrat structurel read-only non possédé par l'outil officiel
|
|
CHECK compilation/typecheck/manifest sans production nécessaire d'artefact
|
|
LINT politique statique stricte
|
|
TEST comportement ciblé ou workspace
|
|
BUILD production d'un artefact réellement nécessaire
|
|
SMOKE preuve d'intégration/processus/frontière runtime
|
|
PACKAGE layout ou archive de livraison
|
|
PUBLISH tag/archive/remote effectivement publiés
|
|
```
|
|
|
|
Une catégorie n'est pas ajoutée pour remplir un quota ; elle doit protéger une propriété affectée par la tranche.
|
|
|
|
## Niveau de preuve
|
|
|
|
Une propriété est vérifiée au niveau le plus fiable et le moins redondant disponible :
|
|
|
|
```text
|
|
compilateur / langage
|
|
-> outil officiel ou linter
|
|
-> manifest / build system
|
|
-> audit structurel read-only
|
|
-> test comportemental
|
|
-> smoke d'intégration lorsque l'environnement le nécessite
|
|
```
|
|
|
|
Une règle qualitative qui exige du jugement humain reste une revue plutôt qu'une regex fragile créée uniquement pour automatiser.
|
|
|
|
## Tests
|
|
|
|
Les tests ciblés sont privilégiés pour le scope directement modifié. Les tests workspace sont utilisés lorsqu'un contrat transverse, un changement de structure ou une phase de consolidation peut invalider plusieurs composants.
|
|
|
|
Les tests unitaires doivent rester indépendants d'Internet et de services externes non contrôlés. Un test d'intégration réel peut utiliser des ressources locales isolées et temporaires lorsqu'il prouve une frontière que des fakes ne démontrent pas correctement.
|
|
|
|
Un test ne modifie pas l'API produit uniquement pour faciliter son accès à des détails internes.
|
|
|
|
## Audits
|
|
|
|
Les audits locaux sont read-only et monotâches autant que raisonnable. Ils contrôlent une propriété du dépôt que le compilateur, rustfmt, Clippy, Cargo, TypeScript, npm ou Vite ne possède pas déjà de manière fiable.
|
|
|
|
Un audit ne doit pas analyser les caches et dépendances générés comme s'ils faisaient partie du source gouverné. Les scripts Markdown locaux ignorent notamment `.git`, `node_modules`, `target` et `builds`.
|
|
|
|
Lorsqu'un audit lexical rencontre un cas que son modèle ne sait pas interpréter sans heuristique fragile, la propriété revient à l'outil officiel ou à une revue humaine plutôt qu'à un faux positif permanent.
|
|
|
|
## Ordre normal
|
|
|
|
Pour une tranche Rust transverse, le formatter officiel normalise d'abord les sources. `cargo fmt --all` est une étape mutante volontaire et doit être exécutée avant tout audit du code Rust ; `cargo fmt --all -- --check` confirme immédiatement l'état obtenu.
|
|
|
|
La séquence habituelle est :
|
|
|
|
```text
|
|
cargo fmt --all
|
|
-> cargo fmt --all -- --check
|
|
-> audits Rust structurels applicables
|
|
-> cargo metadata / cargo check utiles
|
|
-> clippy strict
|
|
-> tests ciblés
|
|
-> tests workspace si justifiés
|
|
-> smokes/builds/packages seulement si le scope les invalide
|
|
-> git diff --cached --check / status
|
|
```
|
|
|
|
Les audits Markdown ou autres contrôles documentaires peuvent être exécutés avant ou après le formatage Rust puisqu'ils ne portent pas sur les sources Rust.
|
|
|
|
Une gate fournie pour exécution dans le shell interactif de l'opérateur ne doit pas modifier durablement les options du shell avec `set -e`, `set -u`, `set -o pipefail` ou une combinaison équivalente. La gate doit laisser chaque commande produire son résultat observable sans risquer de terminer la session terminal de l'opérateur.
|
|
|
|
Pour une tranche Web, les preuves npm/typecheck/build sont ajoutées lorsque `Web/` ou son contrat d'intégration est touché. Une tranche documentaire ou Rust sans diff Web ne rejoue pas automatiquement le frontend.
|
|
|
|
Une phase de stabilisation globale explicitement prévue par le plan (`beta`, `rc` ou clôture stable) peut imposer une preuve de non-régression runtime même sans diff direct sous `Web/` ou dans les launchers. Lorsqu'un plan exige un smoke de stabilisation, cette preuve est obligatoire et ne peut pas être omise au motif que le code runtime n'a pas changé dans la tranche.
|
|
|
|
## Régression et dette externe
|
|
|
|
Un warning provenant d'une dépendance tierce n'est pas automatiquement un `FAIL` si la gate locale ne le traite pas comme tel et si l'outil termine avec succès. Il doit toutefois être reclassé si une mise à jour de toolchain le transforme en rupture réelle ou si la release cible exige zéro warning sur cette frontière.
|
|
|
|
## Traçabilité
|
|
|
|
## Hygiène des fichiers texte
|
|
|
|
Les fichiers texte gouvernés doivent utiliser LF et se terminer par exactement un unique LF. Un suffixe `\n\n` est une ligne vide supplémentaire à EOF et doit être rejeté par la validation lorsqu'il est introduit par la tranche.
|
|
|
|
La validation d'hygiène doit donc distinguer :
|
|
|
|
```text
|
|
...dernière ligne\n valide
|
|
...dernière ligne\n\n invalide
|
|
```
|
|
|
|
Chaque delta liste sa gate exécutable et la matrice conserve le contrat durable. Le history enregistre les résultats réellement observés ; il ne résume pas une prévalidation comme si elle avait été exécutée par l'opérateur.
|