0.0.2-alpha.3
This commit is contained in:
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/001-PROJECT_PROFILE.md -->
|
||||
<!-- version: 11 -->
|
||||
<!-- version: 12 -->
|
||||
|
||||
# Profil du projet Knowledge
|
||||
|
||||
@@ -127,7 +127,7 @@ Les packages matérialisés sont :
|
||||
```text
|
||||
knowledge-domain-lib types métier stables de famille/source
|
||||
knowledge-git-api contrat passif GitRepository provider-neutral
|
||||
knowledge-git-lib implémentation Git générique + configuration physique + état local contrôlé
|
||||
knowledge-git-lib implémentation Git générique + mirror/refresh/resolve/snapshot + état local contrôlé
|
||||
knowledge-sync-api contrat passif RepositoryEventSource
|
||||
knowledge-web-lib composition Actix/Maud/Vite partagée
|
||||
knowledge-pgr-server launcher PGR mince
|
||||
@@ -135,7 +135,7 @@ knowledge-howtos-server launcher HOWTOs mince
|
||||
knowledge-snippets-server launcher snippets mince
|
||||
```
|
||||
|
||||
`knowledge-git-lib` devient réelle en `0.0.2-alpha.2`. `knowledge-app-lib` reste seulement l'owner candidat du cas d'usage de synchronisation partagé et ne sera matérialisée que si l'orchestration réelle démontre cette responsabilité.
|
||||
`knowledge-git-lib` devient réelle en `0.0.2-alpha.2` puis implémente le chemin de lecture Git dans `alpha.3`. `knowledge-app-lib` reste seulement l'owner candidat du cas d'usage de synchronisation partagé et ne sera matérialisée que si l'orchestration réelle démontre cette responsabilité.
|
||||
|
||||
Les responsabilités suivantes restent candidates et non matérialisées :
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md -->
|
||||
<!-- version: 11 -->
|
||||
<!-- version: 12 -->
|
||||
|
||||
# Architecture de fondation Knowledge
|
||||
|
||||
@@ -149,7 +149,7 @@ Pendant `0.0.2`, une racine d'état appartient exclusivement à une instance bac
|
||||
|
||||
### Mirror et refresh
|
||||
|
||||
Une source locale ou remote converge vers un mirror Git contrôlé. `alpha.2` implémente l'initialisation et l'inspection bare minimale ; refresh, résolution et snapshot restent dans les tranches suivantes.
|
||||
Une source locale ou remote converge vers un mirror Git contrôlé. `alpha.2` implémente l'initialisation et l'inspection bare minimale ; `alpha.3` ajoute l'enregistrement explicite des sources physiques, le refresh réel, la résolution et le snapshot derrière `GitRepository`.
|
||||
|
||||
L'initialisation utilise conceptuellement :
|
||||
|
||||
@@ -159,7 +159,7 @@ git clone --mirror [--no-local pour une source locale] -- <source> <mirror>
|
||||
|
||||
Pour une source locale, `--no-local` évite de créer une dépendance par hardlinks/optimisation locale sur le repository éditorial.
|
||||
|
||||
Le refresh réutilise la configuration du remote du mirror et met les refs à jour avec pruning. L'opération doit être idempotente et ne dépend d'aucune API de forge.
|
||||
Le refresh réutilise la configuration du remote du mirror et exécute `remote update --prune`. L'opération est idempotente, initialise le mirror s'il n'existe pas encore et ne dépend d'aucune API de forge.
|
||||
|
||||
### Résolution et snapshot
|
||||
|
||||
@@ -169,15 +169,15 @@ Une référence cible n'est jamais considérée comme identité autoritaire avan
|
||||
git --git-dir=<mirror> rev-parse --verify --end-of-options <reference>^{commit}
|
||||
```
|
||||
|
||||
La valeur obtenue devient `GitRevision`.
|
||||
La valeur obtenue devient `GitRevision`. Le backend valide que l'identité produite est une représentation hexadécimale non vide avant de l'utiliser comme composant de chemin, sans figer une longueur SHA particulière.
|
||||
|
||||
Le snapshot de lecture est ensuite créé comme worktree détaché adressé par cette révision. Un snapshot déjà présent n'est réutilisé qu'après vérification de son `HEAD` et d'un état propre ; une divergence produit une erreur récupérable plutôt qu'un nettoyage destructif silencieux.
|
||||
Le snapshot de lecture est ensuite créé comme worktree détaché adressé par cette révision. `GitSnapshot` expose uniquement la révision autoritaire et le chemin local de lecture. Un snapshot déjà présent n'est réutilisé qu'après vérification de son `HEAD` et d'un état propre ; une divergence produit une erreur récupérable plutôt qu'un nettoyage destructif silencieux.
|
||||
|
||||
Les hooks Git sont désactivés pour les opérations de checkout/worktree appartenant au backend. Les commandes sont exécutées directement sans shell, avec prompts interactifs désactivés et sans journaliser de credential.
|
||||
|
||||
### Scope futur du contrat Git
|
||||
|
||||
Les opérations génériques à plus long terme peuvent inclure `status/diff`, branch, commit, merge/rebase et push. Elles ne sont pas ajoutées en `0.0.2` : la release n'étend le contrat que pour la matérialisation de lecture réellement nécessaire.
|
||||
`alpha.3` étend `GitRepository` uniquement avec `prepare_snapshot`, parce que la matérialisation locale devient effectivement nécessaire au cas d'usage de lecture. Les opérations génériques à plus long terme peuvent inclure `status/diff`, branch, commit, merge/rebase et push. Elles ne sont pas ajoutées en `0.0.2`.
|
||||
|
||||
La baseline conserve au moins trois sources indépendantes (`pgr`, `howtos`, `snippets`) mais le mapping reste configurable et extensible ; aucun `match` codé en dur n'impose exactement trois repositories.
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/plans/002-V0_0_2_GIT_SYNC_PLAN.md -->
|
||||
<!-- version: 5 -->
|
||||
<!-- version: 6 -->
|
||||
|
||||
# Plan 0.0.2 — Git générique et synchronisation de lecture
|
||||
|
||||
@@ -143,7 +143,7 @@ Statut opérateur initial : **FAIL**.
|
||||
|
||||
`alpha.2.fix.1` corrige l'hygiène de fin de fichier, la portée de la gate Markdown, le formatage rustfmt et la construction interne de `GitSourceKey`, mais sa gate reste **FAIL** sur une unique violation `clippy::implicit_return` dans une closure de test.
|
||||
|
||||
`alpha.2.fix.2` corrige exclusivement ce retour implicite, sans modification du backend, de l'API, des dépendances ou du comportement Git.
|
||||
`alpha.2.fix.2` corrige exclusivement ce retour implicite, sans modification du backend, de l'API, des dépendances ou du comportement Git. Sa gate opérateur est **PASS** et ferme `alpha.2`.
|
||||
|
||||
Le delta matérialise le premier backend réel sans encore prétendre couvrir tout le cycle de synchronisation. Les choix concrets de la tranche sont : configuration publique `GitBackendConfig`/`GitSourceConfig`, runner process strictement interne, erreurs publiques redacted par construction et `source-key` hexadécimale déterministe dérivée du `SourceId`.
|
||||
|
||||
@@ -164,17 +164,22 @@ Si la surface « configuration + runner + mirror » ne peut plus être validée
|
||||
|
||||
### alpha.3 — refresh, résolution et snapshot réel
|
||||
|
||||
Compléter le chemin de lecture Git sur de vrais repositories temporaires :
|
||||
Statut opérateur : **à valider**.
|
||||
|
||||
- refresh idempotent du mirror ;
|
||||
- résolution typée d'une référence vers un commit ;
|
||||
La tranche complète le chemin de lecture Git sur de vrais repositories temporaires :
|
||||
|
||||
- enregistrer explicitement les configurations physiques des sources dans `GitBackend` afin d'implémenter réellement le contrat provider-neutral ;
|
||||
- faire implémenter `knowledge-git-api::GitRepository` par `knowledge-git-lib` ;
|
||||
- étendre le contrat uniquement avec `GitSnapshot` / `prepare_snapshot`, maintenant nécessaires à la matérialisation de lecture ;
|
||||
- refresh idempotent du mirror via `remote update --prune` ;
|
||||
- résolution typée d'une référence vers un commit avec `rev-parse --verify --end-of-options ...^{commit}` ;
|
||||
- refus des références invalides ou non résolubles ;
|
||||
- préparation d'un worktree/snapshot détaché adressé par révision ;
|
||||
- validation d'un snapshot existant avant réutilisation ;
|
||||
- validation du `HEAD` et de l'état propre d'un snapshot existant avant réutilisation ;
|
||||
- preuve d'un changement de révision après ajout d'un commit source ;
|
||||
- preuve qu'aucune API de forge n'est nécessaire.
|
||||
|
||||
Les tests doivent exercer la frontière publique du backend et les effets Git réels. Une imitation complète de `git` par mocks ne constitue pas la preuve principale de cette tranche.
|
||||
Les tests doivent exercer la frontière `GitRepository` et les effets Git réels. Une imitation complète de `git` par mocks ne constitue pas la preuve principale de cette tranche. Aucun `knowledge-app-lib`, scheduler ou état persistant n'entre dans `alpha.3`.
|
||||
|
||||
### alpha.4 — cas d'usage de synchronisation
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/validation/001-VALIDATION_MATRIX.md -->
|
||||
<!-- version: 22 -->
|
||||
<!-- version: 23 -->
|
||||
|
||||
# Matrice de validation Knowledge
|
||||
|
||||
@@ -610,3 +610,30 @@ Le second fix reste strictement dans le scope `alpha.2` et doit prouver :
|
||||
- `git diff --cached --check` propre avant commit.
|
||||
|
||||
Le `PASS` de `alpha.2.fix.2` ferme `alpha.2` et autorise uniquement la préparation de `0.0.2-alpha.3`.
|
||||
|
||||
## Gate de `0.0.2-alpha.3`
|
||||
|
||||
La tranche de lecture Git réelle doit prouver :
|
||||
|
||||
- `VERSION = 0.0.2-alpha.3` et `[workspace.package].version` identique ;
|
||||
- history `history/0.0.2/alpha.2.fix.2.md` présent avec statut `PASS` et committé avant application ;
|
||||
- huit packages Cargo exactement ;
|
||||
- `knowledge-git-lib` dépend désormais de `knowledge-domain-lib` et `knowledge-git-api`, sans autre dépendance ;
|
||||
- `knowledge-git-api` étendu uniquement avec le contrat `GitSnapshot` / `prepare_snapshot` nécessaire à la lecture ;
|
||||
- `GitBackend` implémente `knowledge_git_api::GitRepository` et possède l'enregistrement explicite des configurations physiques de source ;
|
||||
- doublons de `SourceId` refusés et source non configurée signalée sans exposer sa localisation ;
|
||||
- refresh du mirror par `git --git-dir <mirror> remote update --prune` ;
|
||||
- résolution par `rev-parse --verify --end-of-options <reference>^{commit}` ;
|
||||
- révision backend validée comme identité hexadécimale non vide avant usage dans un chemin, sans longueur SHA figée ;
|
||||
- snapshot créé par `worktree add --detach -- <path> <revision>` sous `snapshots/<source-key>/<revision>` ;
|
||||
- snapshot existant réutilisé seulement si son `HEAD` correspond exactement à la révision et si `status --porcelain=v1 --untracked-files=all` est vide ;
|
||||
- snapshot divergent ou sale refusé sans suppression silencieuse ;
|
||||
- tests avec vrais repositories Git temporaires prouvant initialisation/refresh/résolution/snapshot, réutilisation idempotente, changement de commit, référence invalide et snapshot sale ;
|
||||
- aucune API de forge, dépendance réseau Rust, PostgreSQL, scheduler, `knowledge-app-lib` ou écriture/push Git ajoutée ;
|
||||
- `cargo fmt --all -- --check`, audits Rust, `cargo metadata`, `cargo check`, Clippy strict, tests ciblés et tests workspace propres ;
|
||||
- `Web/` et `knowledge-sync-api` sans diff ;
|
||||
- `Cargo.lock` toujours ignoré/non suivi ;
|
||||
- `git diff --cached --check` propre avant commit.
|
||||
|
||||
Le `PASS` de `alpha.3` autorise uniquement la préparation de `0.0.2-alpha.4`, consacrée au cas d'usage de synchronisation `Changed` / `Unchanged`.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user