diff --git a/README.md b/README.md index 0d9af38..09916f3 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ - + # Project Governance Rules @@ -13,7 +13,7 @@ Le dépôt officiel est `https://git.sasedev.com/Sasedev/pgr`. PGR est actuellement en phase de fondation `0.0.x`. -La version courante est définie par [`VERSION`](VERSION). La release `0.0.1` établit la gouvernance normative et documentaire de PGR lui-même. La release `0.0.2` ajoute les premiers profils réutilisables Rust/Cargo, Java/Maven/Gradle et Android, ainsi que deux audits Markdown. La release `0.0.3` fournit les premiers modèles Rust/Cargo, deux audits de style Rust facultatifs, l'audit des headers Markdown et la spécification du message manuel de reprise. La série `0.0.x` se poursuit avec les spécifications de skeletons de `0.0.4`. Le contrat transversal et la première fondation de projet gouverné sont désormais matérialisés ; les spécialisations technologiques restent composables et séparées. +La version courante est définie par [`VERSION`](VERSION). La release `0.0.1` établit la gouvernance normative et documentaire de PGR lui-même. La release `0.0.2` ajoute les premiers profils réutilisables Rust/Cargo, Java/Maven/Gradle et Android, ainsi que deux audits Markdown. La release `0.0.3` fournit les premiers modèles Rust/Cargo, deux audits de style Rust facultatifs, l'audit des headers Markdown et la spécification du message manuel de reprise. La série `0.0.x` se poursuit avec les spécifications de skeletons de `0.0.4`. Le contrat transversal, la fondation de projet gouverné et la première specialization Rust/Cargo workspace sont désormais matérialisés ; les autres spécialisations technologiques restent différées tant que leurs pièces requises manquent. ## Entrées principales @@ -30,6 +30,7 @@ La version courante est définie par [`VERSION`](VERSION). La release `0.0.1` é - [`docs/plans/004-V0_0_4_SKELETONS_PLAN.md`](docs/plans/004-V0_0_4_SKELETONS_PLAN.md) — plan actif des skeleton specifications `0.0.4` ; - [`docs/skeletons/000-README.md`](docs/skeletons/000-README.md) — index des skeleton specifications et de leur contrat de composition ; - [`docs/skeletons/001-PROJECT_GOVERNANCE_FOUNDATION.md`](docs/skeletons/001-PROJECT_GOVERNANCE_FOUNDATION.md) — fondation composable de gouvernance locale pour un projet adoptant PGR ; +- [`docs/skeletons/002-RUST_CARGO_WORKSPACE.md`](docs/skeletons/002-RUST_CARGO_WORKSPACE.md) — specialization composable pour un workspace Rust/Cargo gouverné ; - [`docs/validation/001-VALIDATION_MATRIX.md`](docs/validation/001-VALIDATION_MATRIX.md) — matrice de validation. ## Langue et nomenclature diff --git a/VERSION b/VERSION index 7f24a9c..d411fbc 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.0.4-alpha.3 +0.0.4-alpha.4 diff --git a/deltas/0.0.4/alpha.4.md b/deltas/0.0.4/alpha.4.md new file mode 100644 index 0000000..340ae71 --- /dev/null +++ b/deltas/0.0.4/alpha.4.md @@ -0,0 +1,277 @@ + + + +# Delta 0.0.4-alpha.4 — skeleton Rust/Cargo workspace + +## Baseline et version + +Baseline attendue : commit opérateur de `0.0.4-alpha.3`, réalisé après application de `history/0.0.4/alpha.3.md` avec statut `PASS`. + +Le hash de ce commit n'est volontairement pas anticipé : le history `alpha.3` et le présent delta peuvent être livrés dans le même échange, mais restent deux archives séparées et le delta `alpha.4` MUST NOT être appliqué avant le commit de `alpha.3`. + +Version avant application : + +```text +0.0.4-alpha.3 +``` + +Version après application : + +```text +0.0.4-alpha.4 +``` + +## Objet + +Matérialiser la première specialization technologique prévue par le plan `0.0.4` : un skeleton Rust/Cargo workspace composable avec la fondation `001`, les profils `500 + 510`, les cinq templates Rust/Cargo existants et leurs guides d'adaptation. + +La specification doit rendre explicites les décisions destinataire avant copie, la relation entre `VERSION` et la version Cargo, les membres du workspace, l'édition/toolchain, les métadonnées, les dépendances/features, `Cargo.lock`, les lints, les paramètres Rustfmt/Clippy, les artefacts Cargo et la sélection éventuelle des audits de style Rust. + +Aucun template Rust/Cargo ni owner normatif n'est modifié dans cette tranche : la spécialisation doit composer les pièces déjà éprouvées sans universaliser leurs valeurs d'exemple. + +## Scope + +REPLACE : + +```text +VERSION +README.md +docs/000-README.md +docs/skeletons/000-README.md +``` + +ADD : + +```text +docs/skeletons/002-RUST_CARGO_WORKSPACE.md +deltas/0.0.4/alpha.4.md +``` + +DELETE : aucun. + +L'archive delta contient uniquement ces six fichiers complets avec leurs chemins relatifs. Elle ne contient ni `history/0.0.4/alpha.3.md`, livré séparément pour clôturer la tranche précédente, ni `history/0.0.4/alpha.4.md`, qui sera produit après la gate opérateur. + +Les documents suivants restent inchangés : + +```text +docs/rules/220-SKELETONS.md +docs/rules/500-LANGUAGES.md +docs/rules/510-RUST_CARGO.md +docs/templates/001-RUST_CARGO_TOOLING.md +docs/templates/002-CARGO_MANIFESTS.md +docs/validation/002-RUST_STYLE_AUDITS.md +templates/rust-cargo/rustfmt.toml +templates/rust-cargo/clippy.toml +templates/rust-cargo/.cargo/config.toml +templates/rust-cargo/Cargo.toml +templates/rust-cargo/crates/project-core-lib/Cargo.toml +``` + +La tranche exécute donc le plan sans REPLAN et sans déplacer les propriétaires existants. + +## Contenu matérialisé + +`docs/skeletons/002-RUST_CARGO_WORKSPACE.md` : + +- se compose explicitement avec `001-PROJECT_GOVERNANCE_FOUNDATION.md` ; +- sélectionne `500-LANGUAGES.md` et `510-RUST_CARGO.md` sans absorber leurs règles ; +- référence les guides `001-RUST_CARGO_TOOLING.md` et `002-CARGO_MANIFESTS.md` ; +- identifie exactement les cinq templates Rust/Cargo copiables existants ; +- rend explicites les décisions de release unit, membres, édition/toolchain, publication, métadonnées, dépendances/features, lockfile, lints, formatage, Clippy et artefacts ; +- rappelle que `0.1.0`, `2024`, `project-name`, `project-core-lib`, les seuils Clippy et les chemins de build doivent être revus avant adoption ; +- ne fournit aucun `src/lib.rs` ou `src/main.rs` universel ; +- conserve les audits de style Rust comme option explicitement sélectionnée avec corpus ciblé ; +- définit une validation Cargo initiale fondée sur `cargo metadata`, Rustfmt, `cargo check` et Clippy ; +- permet aux futurs profils plateforme/framework de s'ajouter après le workspace sans créer un composite artificiel. + +## Validation opérateur + +Après avoir appliqué `history/0.0.4/alpha.3.md`, committé `0.0.4-alpha.3`, puis appliqué le présent delta, depuis la racine du dépôt : + +```bash +test "$(cat VERSION)" = '0.0.4-alpha.4' +test -f history/0.0.4/alpha.3.md +test -f deltas/0.0.4/alpha.4.md +test -f docs/skeletons/002-RUST_CARGO_WORKSPACE.md +test ! -e history/0.0.4/alpha.4.md + +grep -Fx '' README.md +grep -Fx '' docs/000-README.md +grep -Fx '' docs/skeletons/000-README.md +grep -Fx '' docs/skeletons/002-RUST_CARGO_WORKSPACE.md + +grep -F '002-RUST_CARGO_WORKSPACE.md' README.md +grep -F '002-RUST_CARGO_WORKSPACE.md' docs/000-README.md +grep -F '002-RUST_CARGO_WORKSPACE.md' docs/skeletons/000-README.md + +python3 -B -m unittest discover -s tests -v + +python3 -B scripts/audit_markdown_headers.py \ + README.md RULES.md ROADMAP.md CHANGELOG.md docs deltas history prompts +python3 -B scripts/audit_markdown_tables.py \ + README.md RULES.md ROADMAP.md CHANGELOG.md docs deltas history prompts +python3 -B scripts/audit_markdown_links.py \ + README.md RULES.md ROADMAP.md CHANGELOG.md docs deltas history prompts + +python3 -B - <<'PY' +from pathlib import Path +import re +import tomllib + +histories = {path.name for path in Path('history/0.0.4').glob('*.md')} +assert histories == {'alpha.1.md', 'alpha.2.md', 'alpha.3.md'}, histories +for name in sorted(histories): + text = Path('history/0.0.4', name).read_text(encoding='utf-8') + assert re.search(r'## Statut\s+PASS\s', text), name + +skeletons = sorted(path.name for path in Path('docs/skeletons').glob('*.md')) +assert skeletons == [ + '000-README.md', + '001-PROJECT_GOVERNANCE_FOUNDATION.md', + '002-RUST_CARGO_WORKSPACE.md', +], skeletons + +text = Path('docs/skeletons/002-RUST_CARGO_WORKSPACE.md').read_text(encoding='utf-8') +for phrase in ( + '## Applicabilité et composition', + '## Owners, guides et artefacts sélectionnés', + '## Décisions destinataire avant copie', + '## Matérialisation du workspace', + '### Cargo.lock', + '### Audits de style facultatifs', + '## Validation initiale', + '## Ordre de composition et extensions', + '## Overrides et exceptions', + '## Hors scope', +): + assert phrase in text, phrase + +for owner in ('500-LANGUAGES.md', '510-RUST_CARGO.md'): + assert owner in text, owner + +for template in ( + 'templates/rust-cargo/rustfmt.toml', + 'templates/rust-cargo/clippy.toml', + 'templates/rust-cargo/.cargo/config.toml', + 'templates/rust-cargo/Cargo.toml', + 'templates/rust-cargo/crates/project-core-lib/Cargo.toml', +): + assert template in text, template + +for path in ( + Path('templates/rust-cargo/rustfmt.toml'), + Path('templates/rust-cargo/clippy.toml'), + Path('templates/rust-cargo/.cargo/config.toml'), + Path('templates/rust-cargo/Cargo.toml'), + Path('templates/rust-cargo/crates/project-core-lib/Cargo.toml'), +): + with path.open('rb') as stream: + tomllib.load(stream) + +print('Rust/Cargo skeleton audit: clean (alpha.1-alpha.3 PASS baseline, five templates parsed)') +PY + +command -v cargo +command -v rustfmt +cargo --version +rustc --version +rustfmt --version +cargo clippy --version + +tmp="$(mktemp -d)" +trap 'rm -rf "$tmp"' EXIT +mkdir -p "$tmp/.cargo" "$tmp/crates/smoke-core-lib/src" +cp templates/rust-cargo/Cargo.toml "$tmp/Cargo.toml" +cp templates/rust-cargo/rustfmt.toml "$tmp/rustfmt.toml" +cp templates/rust-cargo/clippy.toml "$tmp/clippy.toml" +cp templates/rust-cargo/.cargo/config.toml "$tmp/.cargo/config.toml" +cp templates/rust-cargo/crates/project-core-lib/Cargo.toml "$tmp/crates/smoke-core-lib/Cargo.toml" +printf '1.2.3\n' > "$tmp/VERSION" + +python3 -B - "$tmp" <<'PY' +from pathlib import Path +import sys + +root = Path(sys.argv[1]) + +replacements = { + root / 'Cargo.toml': ( + ('# file: templates/rust-cargo/Cargo.toml', '# file: Cargo.toml'), + ('members = ["crates/project-core-lib"]', 'members = ["crates/smoke-core-lib"]'), + ('version = "0.1.0"', 'version = "1.2.3"'), + ), + root / 'rustfmt.toml': ( + ('# file: templates/rust-cargo/rustfmt.toml', '# file: rustfmt.toml'), + ), + root / 'clippy.toml': ( + ('# file: templates/rust-cargo/clippy.toml', '# file: clippy.toml'), + ), + root / '.cargo/config.toml': ( + ('# file: templates/rust-cargo/.cargo/config.toml', '# file: .cargo/config.toml'), + ('../builds/project-name/target', 'target-smoke'), + ), + root / 'crates/smoke-core-lib/Cargo.toml': ( + ('# file: templates/rust-cargo/crates/project-core-lib/Cargo.toml', '# file: crates/smoke-core-lib/Cargo.toml'), + ('name = "project-core-lib"', 'name = "smoke-core-lib"'), + ), +} + +for path, pairs in replacements.items(): + text = path.read_text(encoding='utf-8') + for old, new in pairs: + assert old in text, (path, old) + text = text.replace(old, new) + path.write_text(text, encoding='utf-8') + +for path in root.rglob('*'): + if path.is_file() and path.name != 'Cargo.lock': + text = path.read_text(encoding='utf-8') + assert 'project-name' not in text, path + assert 'project-core-lib' not in text, path +PY + +cat > "$tmp/crates/smoke-core-lib/src/lib.rs" <<'RS' +//! Minimal crate used to validate the PGR Rust/Cargo templates. + +/// Returns the deterministic smoke value. +pub fn smoke_value() -> u8 { + return 1; +} +RS + +( + cd "$tmp" + cargo metadata --format-version 1 --no-deps >/dev/null + cargo fmt --all -- --check + cargo check --workspace + cargo clippy --workspace --all-targets --all-features -- -D warnings +) + +rm -rf "$tmp" +trap - EXIT + +git diff --check +git add VERSION README.md docs/000-README.md \ + docs/skeletons/000-README.md \ + docs/skeletons/002-RUST_CARGO_WORKSPACE.md \ + deltas/0.0.4/alpha.4.md +git diff --cached --check +git status --short +``` + +## Revue opérateur + +En complément des commandes, vérifier que : + +- `002` reste une specialization composable de `001` et ne redéfinit pas les owners généraux ; +- les cinq templates sont référencés comme artefacts à adapter, jamais comme valeurs universelles ; +- la politique `Cargo.lock`, les membres, dépendances/features, métadonnées et éventuelles exceptions de lints/safety restent des décisions explicites du projet ; +- les audits Rust facultatifs ne sont ni copiés ni exécutés sans sélection de leur convention et de leur corpus ; +- aucune règle Java/Android/Web/JNI/Tauri ou autre plateforme/framework n'entre dans la tranche ; +- l'instanciation temporaire prouve l'adoption minimale des templates sans ajouter de workspace Rust au dépôt PGR. + +## Transition + +PASS : produire `history/0.0.4/alpha.4.md`, l'appliquer puis committer `0.0.4-alpha.4`. La tranche suivante prévue par le plan est `0.0.4-beta.1`, consacrée à la réconciliation interne de la release : ownership, liens, index, duplication normative, valeurs d'exemple, limites des audits et confirmation des domaines différés. + +FAIL : rester dans le scope de `alpha.4` via `alpha.4.fix.1` sauf si l'instanciation démontre qu'un template ou une décision normative existante est insuffisante, auquel cas déclencher le REPLAN prévu par le plan. diff --git a/docs/000-README.md b/docs/000-README.md index 4982718..0860259 100644 --- a/docs/000-README.md +++ b/docs/000-README.md @@ -1,5 +1,5 @@ - + # Documentation PGR @@ -25,6 +25,7 @@ Les templates techniques copiables sous `templates/` restent séparés des instr - [`plans/004-V0_0_4_SKELETONS_PLAN.md`](plans/004-V0_0_4_SKELETONS_PLAN.md) — cadrage actif des premières skeleton specifications et de leur composition ; - [`skeletons/000-README.md`](skeletons/000-README.md) — contrat de collection des skeleton specifications ; - [`skeletons/001-PROJECT_GOVERNANCE_FOUNDATION.md`](skeletons/001-PROJECT_GOVERNANCE_FOUNDATION.md) — fondation de gouvernance locale composable et sans spécialisation technologique ; +- [`skeletons/002-RUST_CARGO_WORKSPACE.md`](skeletons/002-RUST_CARGO_WORKSPACE.md) — specialization Rust/Cargo workspace composable avec la fondation et les cinq templates existants ; - [`templates/001-RUST_CARGO_TOOLING.md`](templates/001-RUST_CARGO_TOOLING.md) et [`templates/002-CARGO_MANIFESTS.md`](templates/002-CARGO_MANIFESTS.md) — adaptation des cinq fichiers Rust/Cargo copiables ; - [`templates/003-NEW_SESSION_PROMPT.md`](templates/003-NEW_SESSION_PROMPT.md) — spécification du message manuel après une stable publiée ; - [`validation/001-VALIDATION_MATRIX.md`](validation/001-VALIDATION_MATRIX.md) et [`validation/002-RUST_STYLE_AUDITS.md`](validation/002-RUST_STYLE_AUDITS.md) — gates PGR et limites des audits de style Rust facultatifs. diff --git a/docs/skeletons/000-README.md b/docs/skeletons/000-README.md index 8d82a07..69dd392 100644 --- a/docs/skeletons/000-README.md +++ b/docs/skeletons/000-README.md @@ -1,5 +1,5 @@ - + # Index des skeleton specifications PGR @@ -18,7 +18,8 @@ Une specification peut se composer avec une fondation plus générale, mais la c ## Specifications actives - [`001-PROJECT_GOVERNANCE_FOUNDATION.md`](001-PROJECT_GOVERNANCE_FOUNDATION.md) — fondation composable pour établir la gouvernance locale, la version, la documentation minimale, le workflow retenu et sa validation initiale sans imposer d'architecture applicative. +- [`002-RUST_CARGO_WORKSPACE.md`](002-RUST_CARGO_WORKSPACE.md) — specialization composable d'un workspace Rust/Cargo fondée sur `001`, les profils `500 + 510`, les cinq templates Rust/Cargo et une validation réelle de la toolchain. -Le plan [`../plans/004-V0_0_4_SKELETONS_PLAN.md`](../plans/004-V0_0_4_SKELETONS_PLAN.md) prévoit ensuite une specialization Rust/Cargo fondée sur cette fondation, les profils `500 + 510` et les templates déjà disponibles. Les familles Java/Android, Web, JNI, Tauri et autres domaines sans pièces suffisantes restent différées. +Les familles Java/Android, Web, JNI, Tauri et autres domaines sans pièces suffisantes restent différées selon le plan [`../plans/004-V0_0_4_SKELETONS_PLAN.md`](../plans/004-V0_0_4_SKELETONS_PLAN.md). Aucun fichier placeholder ne doit être ajouté pour réserver un skeleton futur. diff --git a/docs/skeletons/002-RUST_CARGO_WORKSPACE.md b/docs/skeletons/002-RUST_CARGO_WORKSPACE.md new file mode 100644 index 0000000..65021c5 --- /dev/null +++ b/docs/skeletons/002-RUST_CARGO_WORKSPACE.md @@ -0,0 +1,206 @@ + + + +# Skeleton — Rust/Cargo workspace + +## Objectif + +Cette specification décrit la specialization Rust/Cargo d'un projet gouverné par PGR lorsque plusieurs packages Rust partagent réellement une même unité de release, une politique Cargo commune ou une validation de workspace commune. + +Elle se compose avec [`001-PROJECT_GOVERNANCE_FOUNDATION.md`](001-PROJECT_GOVERNANCE_FOUNDATION.md), sélectionne les profils [`../rules/500-LANGUAGES.md`](../rules/500-LANGUAGES.md) et [`../rules/510-RUST_CARGO.md`](../rules/510-RUST_CARGO.md), puis utilise les templates et guides Rust/Cargo déjà présents dans PGR. Le contrat transversal des skeletons reste possédé par [`../rules/220-SKELETONS.md`](../rules/220-SKELETONS.md). + +Cette specification ne transforme pas PGR en générateur Cargo et ne crée aucune dépendance build ou runtime vers le dépôt PGR après instanciation. + +## Applicabilité et composition + +Appliquer ce skeleton lorsqu'un projet utilise Rust avec Cargo et qu'un workspace représente réellement son unité de gouvernance ou de release. + +La composition normale est : + +```text +001-PROJECT_GOVERNANCE_FOUNDATION + ↓ +500-LANGUAGES + ↓ +510-RUST_CARGO + ↓ +002-RUST_CARGO_WORKSPACE +``` + +Un dépôt contenant plusieurs unités de release indépendantes ne doit pas être forcé dans un workspace à version globale fictive. Un framework, une plateforme, WASM, Android, Tauri, une FFI ou un autre scope plus spécifique peut ajouter ses propres règles sans modifier le contrat Rust/Cargo général. + +## Owners, guides et artefacts sélectionnés + +Les responsabilités générales de version, workflow, documentation et validation sont déjà couvertes par la fondation `001`. La présente specialization ajoute : + +```text +docs/rules/500-LANGUAGES.md + contrat commun langage/écosystème + +docs/rules/510-RUST_CARGO.md + workspace, manifests, dépendances, lints, safety, formatage et validation Cargo + +docs/templates/001-RUST_CARGO_TOOLING.md + adaptation de rustfmt.toml, clippy.toml et .cargo/config.toml + +docs/templates/002-CARGO_MANIFESTS.md + adaptation du manifest workspace et du manifest membre +``` + +Les cinq artefacts techniques copiables sélectionnés sont : + +```text +templates/rust-cargo/rustfmt.toml +templates/rust-cargo/clippy.toml +templates/rust-cargo/.cargo/config.toml +templates/rust-cargo/Cargo.toml +templates/rust-cargo/crates/project-core-lib/Cargo.toml +``` + +[`../validation/002-RUST_STYLE_AUDITS.md`](../validation/002-RUST_STYLE_AUDITS.md) est seulement une option supplémentaire. Les scripts `audit_rust_blank_lines.py`, `audit_rust_const_blocks.py` et `_rust_audit_common.py` ne sont copiés que si le projet choisit explicitement les conventions correspondantes et sait quels fichiers Rust doivent être audités. + +## Décisions destinataire avant copie + +Avant de considérer la specialization comme instanciée, résoudre explicitement au minimum : + +1. le release unit gouverné et la relation entre son `VERSION` et `[workspace.package].version` ; +2. la liste réelle des packages membres, leurs noms, leurs rôles et leurs chemins ; +3. l'édition Rust, le resolver Cargo et la toolchain stable compatible ; +4. la politique de publication et les métadonnées réelles communes (`license`, `repository`, `authors`) lorsqu'elles existent ; +5. les dépendances réellement partagées, leurs contraintes de version et les features qui doivent rester locales à chaque membre ; +6. la politique de versionnement de `Cargo.lock` adaptée au type de produit ; +7. les niveaux de lints hérités, les éventuelles exceptions locales et tout besoin réel d'`unsafe` dans un scope étroit ; +8. les paramètres `rustfmt.toml` et `clippy.toml` à conserver ou adapter ; +9. l'emplacement des artefacts Cargo et l'identifiant unique utilisé dans `.cargo/config.toml` si cette politique externe au dépôt est retenue ; +10. les audits de style Rust facultatifs réellement adoptés et leur corpus exact ; +11. les validations Cargo réellement nécessaires au code et aux manifests créés. + +Les valeurs `0.1.0`, `2024`, `project-name`, `project-core-lib`, les seuils Clippy et les chemins de build présents dans les templates sont des exemples ou baselines à revoir. Ils ne deviennent jamais des valeurs universelles par simple copie. + +## Matérialisation du workspace + +### Fondation gouvernée + +Appliquer d'abord la fondation `001` et résoudre ses décisions générales. Ne recopier ni le workflow ni la structure documentaire complète de PGR lorsqu'ils ne sont pas nécessaires au projet destinataire. + +La version canonique du release unit doit être décidée avant d'adapter les manifests. Pour un train de release Cargo unique, `[workspace.package].version` reflète cette version selon `510-RUST_CARGO.md`. + +### Manifest workspace + +Copier `templates/rust-cargo/Cargo.toml` vers `Cargo.toml`, puis : + +- adapter le header `# file:` et démarrer la révision locale selon la convention documentaire retenue ; +- remplacer `members` par les packages réellement présents ; +- remplacer la version d'exemple par la version du release unit lorsque le workspace partage une seule release ; +- aligner `edition` et `resolver` sur la toolchain réellement choisie ; +- décider explicitement `publish` et les métadonnées communes ; +- ajouter sous `[workspace.dependencies]` uniquement les dépendances réellement partagées ; +- conserver, adapter ou documenter les niveaux de lints selon le profil local retenu. + +Le projet ne doit pas remplir les champs manquants avec des identités fictives provenant de PGR, KSP ou Games. + +### Packages membres + +Pour chaque crate réellement nécessaire, utiliser `templates/rust-cargo/crates/project-core-lib/Cargo.toml` comme exemple de manifest membre puis adapter son chemin et son nom. + +`project-core-lib` n'est pas un nom de crate imposé. Une crate bibliothèque, binaire ou spécialisée doit conserver le layout et les héritages qui correspondent à son rôle réel. + +Lorsque le membre hérite de la politique commune, `version.workspace = true`, `edition.workspace = true`, `publish.workspace = true` et `[lints] workspace = true` restent cohérents. Une exception locale, notamment de lint ou de safety, doit suivre le contrat de `510-RUST_CARGO.md` et ne pas affaiblir silencieusement les autres membres. + +Le code source minimal requis par Cargo appartient au projet destinataire. PGR ne fournit pas de `src/lib.rs` ou `src/main.rs` universel, car leur contenu dépend du rôle réel de la crate. + +### Outillage Rust/Cargo + +Copier et adapter : + +```text +rustfmt.toml +clippy.toml +.cargo/config.toml +``` + +Suivre [`../templates/001-RUST_CARGO_TOOLING.md`](../templates/001-RUST_CARGO_TOOLING.md) pour leurs décisions d'adaptation. + +L'édition de `rustfmt.toml` doit rester cohérente avec le workspace. Les seuils de `clippy.toml` doivent être revus au regard des API réelles. Dans `.cargo/config.toml`, remplacer `project-name` ou choisir un autre emplacement d'artefacts ; ne pas copier un chemin machine ou un identifiant appartenant à un autre projet. + +### Cargo.lock + +Décider explicitement si `Cargo.lock` est versionné selon le type de produit, le mode de publication et le besoin de reproductibilité. La présence ou l'absence du lockfile dans un projet source historique ne constitue pas une règle suffisante pour le nouveau workspace. + +### Audits de style facultatifs + +Si le projet adopte les conventions documentées dans [`../validation/002-RUST_STYLE_AUDITS.md`](../validation/002-RUST_STYLE_AUDITS.md), copier les trois scripts concernés et adapter leurs headers à leurs chemins locaux. + +La sélection des fichiers doit rester explicite. En particulier, l'audit des blocs de constantes ne doit jamais réordonner une table de protocole, une séquence de migrations ou toute autre structure dont l'ordre possède une sémantique propre. + +Ne pas copier ces scripts uniquement parce qu'ils existent dans PGR. + +## Validation initiale + +Une instanciation minimale doit d'abord prouver que les manifests adaptés décrivent bien le workspace voulu, puis que les outils Rust/Cargo retenus acceptent la baseline réelle. + +Lorsque la toolchain est disponible et que du code source minimal ou réel existe, la séquence normale comprend : + +```bash +cargo metadata --format-version 1 --no-deps +cargo fmt --all -- --check +cargo check --workspace +cargo clippy --workspace --all-targets --all-features -- -D warnings +``` + +Ajouter des tests ciblés pour les crates qui possèdent déjà un comportement à vérifier. Un `cargo build` n'est nécessaire que lorsqu'un artefact de build doit réellement être produit. + +Si les audits de style facultatifs ont été sélectionnés, les exécuter après le formatage sur les seuls chemins concernés. + +La validation doit aussi confirmer : + +```text +CHECK VERSION et workspace.package.version cohérents pour un train de release unique +CHECK aucun placeholder project-name/project-core-lib non résolu dans les fichiers adoptés +CHECK édition Rust cohérente entre Cargo.toml et rustfmt.toml +CHECK membres du workspace existants et correctement nommés +CHECK politique Cargo.lock explicitement décidée +CHECK artefacts Cargo hors des livraisons source selon la politique locale +REVIEW dépendances/features, lints et métadonnées réellement nécessaires +REVIEW aucune specialization plateforme/framework ajoutée sans besoin réel +``` + +Pour valider les templates PGR eux-mêmes, une instanciation temporaire minimale peut remplacer les placeholders, créer une crate source triviale et exécuter les commandes Cargo ci-dessus. Cette preuve vérifie l'adoption des templates sans transformer le dépôt PGR en workspace Rust. + +Une prévalidation PGR ou générateur ne remplace jamais la gate opérateur autoritaire du projet destinataire. + +## Ordre de composition et extensions + +La specialization Rust/Cargo doit être appliquée après `001` lorsqu'elle l'utilise comme fondation. Les profils plateforme ou framework viennent ensuite uniquement s'ils sont applicables. + +Une specialization plus précise peut : + +- ajouter des packages ou cibles spécifiques ; +- imposer une matrice de toolchain ou de SDK ; +- raffiner la politique d'artefacts ou de lockfile ; +- ajouter des features, dépendances ou validations propres à son scope ; +- définir une exception locale de safety strictement justifiée. + +Elle ne doit pas réécrire les règles générales Cargo ou inventer un nouveau workspace composite si les owners existants suffisent. + +## Overrides et exceptions + +Toute divergence par rapport aux templates ou au profil `510` doit identifier le choix concerné, son scope et sa raison lorsqu'elle affecte le contrat durable du projet. + +Un projet peut notamment choisir un layout sans `crates/`, un autre chemin d'artefacts, une autre largeur Rustfmt, une politique de lockfile différente, des seuils Clippy différents ou une crate à lints locaux. Ces choix restent locaux et ne modifient pas les defaults PGR pour les autres projets. + +## Hors scope + +Cette specification ne définit pas : + +- un nom universel de workspace ou de crate ; +- une version Rust ou Cargo exacte à pinner sans justification ; +- une liste universelle de dépendances ou features ; +- une politique `Cargo.lock` identique pour bibliothèques et applications ; +- une architecture applicative au-delà du workspace Cargo ; +- une plateforme, un framework, WASM, Android, Tauri ou une FFI ; +- un CI/CD, packaging ou mécanisme de publication universel ; +- une obligation de copier les audits Rust facultatifs ; +- un `src/lib.rs` ou `src/main.rs` générique sans rôle réel. + +Les spécialisations futures doivent rester composables au-dessus de ce skeleton plutôt que modifier rétroactivement son scope. diff --git a/history/0.0.4/alpha.4.md b/history/0.0.4/alpha.4.md new file mode 100644 index 0000000..a60ee98 --- /dev/null +++ b/history/0.0.4/alpha.4.md @@ -0,0 +1,142 @@ + + + +# History 0.0.4-alpha.4 — skeleton Rust/Cargo workspace + +## Statut + +FAIL + +La tranche `0.0.4-alpha.4` n'est pas enregistrée `PASS` telle quelle. + +Le contenu documentaire, les audits PGR et l'exécution réelle de Cargo sont cohérents, mais une assertion obligatoire de la gate d'instanciation a échoué : après adaptation du template `.cargo/config.toml`, le commentaire de guidance conservait encore le placeholder littéral `project-name`. + +## Baseline + +La tranche précédente `0.0.4-alpha.3` a été committée et poussée sous le commit observé : + +```text +5471ea6 +``` + +Version contrôlée après application de `alpha.4` : + +```text +0.0.4-alpha.4 +``` + +Les fichiers attendus sont présents et `history/0.0.4/alpha.4.md` était absent avant cette validation. + +## Contrôles réussis observés + +Les `15` tests Python ont tous réussi : + +```text +Ran 15 tests in 0.251s +OK +``` + +Les audits Markdown ont réussi : + +```text +Markdown header audit: clean (111 file(s)) +Markdown table audit: clean (3 table(s), 111 file(s)) +Markdown link audit: clean (113 local link(s), 111 file(s)) +``` + +L'audit structurel du skeleton Rust/Cargo a également réussi : + +```text +Rust/Cargo skeleton audit: clean (alpha.1-alpha.3 PASS baseline, five templates parsed) +``` + +Il confirme notamment les trois skeletons attendus, les histories `alpha.1` à `alpha.3` en `PASS`, les owners `500-LANGUAGES.md` et `510-RUST_CARGO.md`, les cinq templates Rust/Cargo référencés et leur parsing TOML. + +La toolchain opérateur observée est disponible : + +```text +cargo 1.94.1 (29ea6fb6a 2026-03-24) +rustc 1.94.1 (e408947bf 2026-03-25) +rustfmt 1.8.0-stable (e408947bfd 2026-03-25) +clippy 0.1.94 (e408947bfd 2026-03-25) +``` + +Après l'assertion défectueuse, les commandes Cargo ont été exécutées sur le workspace temporaire et ont réussi : + +```text +cargo metadata --format-version 1 --no-deps +cargo fmt --all -- --check +cargo check --workspace +cargo clippy --workspace --all-targets --all-features -- -D warnings +``` + +`cargo check` et `cargo clippy` ont tous deux terminé avec succès pour `smoke-core-lib v1.2.3`. + +`git diff --check` et `git diff --cached --check` n'ont produit aucun diagnostic. Le scope Git observé avant le présent history est exactement : + +```text +M README.md +M VERSION +A deltas/0.0.4/alpha.4.md +M docs/000-README.md +M docs/skeletons/000-README.md +A docs/skeletons/002-RUST_CARGO_WORKSPACE.md +``` + +## Défaut exact + +La gate copie `templates/rust-cargo/.cargo/config.toml`, puis remplace le chemin : + +```text +../builds/project-name/target +``` + +par : + +```text +target-smoke +``` + +Les deux valeurs `target-dir` et `build-dir` sont donc adaptées correctement. Cependant, le template contient aussi le commentaire : + +```text +# Replace project-name with a unique name before using this configuration. +``` + +Le script d'instanciation ne remplace pas ce commentaire, puis vérifie volontairement qu'aucun placeholder `project-name` ou `project-core-lib` ne subsiste dans les fichiers copiés. L'assertion échoue donc sur : + +```text +/tmp/.../.cargo/config.toml +``` + +avec : + +```text +AssertionError +``` + +Le workspace généré reste compilable, comme le montrent les commandes Cargo réussies ensuite, mais une commande obligatoire de la gate a échoué. La tranche ne peut donc pas être déclarée `PASS`. + +## Décision + +Aucun REPLAN n'est requis. + +Le défaut appartient uniquement au smoke d'instanciation défini dans la gate de `alpha.4`. Les règles, le skeleton `002` et les cinq templates livrés restent inchangés. + +La correction reste strictement locale : + +```text +0.0.4-alpha.4.fix.1 +``` + +Le delta `alpha.4` livré reste un snapshot historique et n'est pas réécrit. Le fix corrige la procédure de smoke en adaptant aussi le commentaire de `.cargo/config.toml`, puis rejoue les contrôles nécessaires. + +## Résultat + +`0.0.4-alpha.4` est enregistré `FAIL`. + +La seule transition autorisée est : + +```text +0.0.4-alpha.4.fix.1 +```