fix(ci): discard the stale doc tree restored from the cache

[pierrick-fonquerne]

Problem

The Documentation job fails on every pull request that changes Cargo.lock:

Error: failed to remove directory `/home/runner/work/.../target/doc/<crate>/...`

Caused by:
  No such file or directory (os error 2)

The caching action prunes the artifacts of the workspace crates before saving
target/, which leaves the target/doc directory tree in place without its
contents. On restore, the stale output collector of rustdoc walks that tree and
trips over the phantom directories.

Why the job stays green on main

On main the cache key hits exactly, cargo considers every output fresh and
never enters the cleanup code path. The failure only shows up when the key
misses and falls back to a prefix restore, which is exactly what a changed
Cargo.lock does. In practice: every dependency bump, now and in the future.

The incriminated path changes from one run to the next, because it depends on
which crate the collector reaches first. That varying path is the signature of
restored state, not of a regression in the code.

Fix

One cargo clean --doc step before cargo doc. It removes target/doc and
nothing else, so the dependency cache is preserved and the cost is a few
seconds of documentation regeneration.

This is the same fix already merged on hexeract (ebb55f4), where it was
proven by rebasing a blocked dependency bump on top of it and watching the
Documentation job turn green.

[github-actions]

Team Review

Verdict: SHIP ✅ · 0 confirmed · 3 contested

🇬🇧 English

Overview
This PR modifies the CI workflow to add a cargo clean --doc step before generating documentation. The change aims to prevent ENOENT errors caused by stale cache files in the documentation build process. The implementation is straightforward and addresses a specific reliability issue, though it introduces a minor security consideration.

Strengths

• Prevents ENOENT errors in the documentation build process by cleaning stale cache files.
• Improves the reliability of the documentation generation step in CI.

⚠️ Contested (adversarial verification)

• 🟡 design .github/workflows/ci.yml: The comment explaining the reason for cargo clean --doc is redundant as the purpose is already clear from the context and the command itself. (via correctness)
  • The comment does not explain the purpose of the command, but rather the reason for using it.
• 🟡 security .github/workflows/ci.yml:110: The cargo clean --doc command could potentially be exploited to remove critical files if not properly secured, though the risk is low in this CI context. (via security)
  • The cargo clean --doc command is intentionally added to address a specific issue with the cache and rustdoc, not a security concern.
• 🟡 performance .github/workflows/ci.yml: The addition of cargo clean --doc before cargo doc ensures a consistent build environment but adds a few seconds to the build time. (via architecture, performance)
  • The finding is theoretical and not backed by observable evidence or measurable impact.

🇫🇷 Français

Vue d'ensemble
Cette PR modifie le workflow CI pour ajouter une étape cargo clean --doc avant la génération de la documentation. Le changement vise à prévenir les erreurs ENOENT causées par des fichiers de cache obsolètes dans le processus de construction de la documentation. L'implémentation est directe et résout un problème de fiabilité spécifique, bien qu'elle introduise une considération mineure de sécurité.

Points forts

• Prévient les erreurs ENOENT dans le processus de construction de la documentation en nettoyant les fichiers de cache obsolètes.
• Améliore la fiabilité de l'étape de génération de la documentation dans le CI.

⚠️ Contestés (vérification adversariale)

• 🟡 design .github/workflows/ci.yml: Le commentaire expliquant la raison de cargo clean --doc est redondant car l'objectif est déjà clair d'après le contexte et la commande elle-même. (via correctness)
  • Le commentaire n'explique pas l'objectif de la commande, mais plutôt la raison de son utilisation.
• 🟡 security .github/workflows/ci.yml:110: La commande cargo clean --doc pourrait potentiellement être exploitée pour supprimer des fichiers critiques si elle n'est pas correctement sécurisée, bien que le risque soit faible dans ce contexte CI. (via security)
  • La commande cargo clean --doc est intentionnellement ajoutée pour résoudre un problème spécifique avec le cache et rustdoc, et non un problème de sécurité.
• 🟡 performance .github/workflows/ci.yml: L'ajout de cargo clean --doc avant cargo doc garantit un environnement de construction cohérent mais ajoute quelques secondes au temps de construction. (via architecture, performance)
  • La constatation est théorique et n'est pas étayée par des preuves observables ou un impact mesurable.

---

Agents: Correctness, Security, Architecture, Performance
Findings: 4 raw -> 3 merged
Model: codestral-latest + mistral-large-latest · Diff: 1 file(s)