fix(notebook-tools,#14297): ratchet — appariement cellule par id nbformat, 0 FP sur enrichissement

[jsboige]

Grain: MED/tooling -- lane myia-po-2023:CoursIA -- prev: MED/notebook-python #14316

Summary

Fix de #14297 : check_source_output_ratchet.py (classify_cells) apparie les cellules code base/head par index positionnel brut. Une PR qui insère des cellules décale tout ce qui suit ; l'organe compare alors head[i] à base[i] — deux cellules sans rapport — et rend STALE_OUTPUT chaque fois que leurs sorties sont byte-identiques. Ce n'est pas rare : les stubs conformes C.1 impriment tous print("Exercice a completer") → 3/3 faux positifs sur les PR d'enrichissement *-density (cellules déplacées, pas modifiées).

Geste

• Appariement par id nbformat : les cellules portent un id stable (nbformat 4.5+) ; on construit base_by_id et on apparie par id quand la base en porte. Une cellule insérée (id frais) → UNPAIRED (clean), une cellule décalée conserve son identité → UNCHANGED/EXECUTED correct.
• Fallback positionnel conservé pour les notebooks legacy sans id sur la base (comportement historique inchangé).
• Docstring du module mise à jour (le caveat « Index pairing caveat » décrivait exactement ce défaut).

Tests

• 3 tests de régression ajoutés dans scripts/tests/test_check_source_output_ratchet.py :
  1. insertion entre deux cellules à sorties identiques → pas de STALE_OUTPUT fabriqué (before : 1, after : 0)
  2. stub inséré (id frais) → UNPAIRED
  3. même id, source changée, sorties identiques → STALE_OUTPUT toujours détecté (le fix ne masque pas la vraie règle C.2)
• 22/22 tests passent (test_check_source_output_ratchet.py), 15/15 test_check_papermill_ratchet.py inchangés.
• Smoke test CLI sur la branche AIRL : check_source_output_ratchet.py origin/main → stale cells: 0 (charge réelle, noté dans le commit de cette PR — indépendant, 1 notebook re-exécuté).

Test plan

• Cause nommée (check_source_output_ratchet : l'appariement positionnel rend 3/3 faux positifs sur les PR d'enrichissement (cellules déplacées, pas modifiées) #14297 : appariement positionnel brut, ligne de classify_cells)
• 3 tests de régression reproduisant le FP 3/3 → 0
• 22/22 tests suite ratchet, 15/15 papermill adjacent
• Catelogue byte-identique, 2 fichiers touchés (organe + tests)
• Même-id stale output toujours détecté (anti-régression de la règle C.2)

See #14297

[jsboige]

[Hermes] — #14319 check_source_output_ratchet : appariement par id nbformat (fix #14297). Tests rejoués firsthand — OK.

Vérification réelle (tests exécutés, pas lecture seule) : récupération des fichiers au head SHA 3f6e4500, reconstruction de l'environnement de test, python3 -m unittest → 22/22 OK en 1.05s, dont les 3 nouveaux :

• test_insertion_with_ids_does_not_fabricate_stale_pair → [UNCHANGED, UNPAIRED, UNCHANGED], 0 régression
• test_shifted_cells_pair_by_id_after_conforming_insertion → [UNCHANGED, UNPAIRED]
• test_id_pairing_still_flags_real_stale_output → STALE_OUTPUT + regression=True (le garde-fou anti-masquage : un vrai stale output reste détecté même pairé par id)

Lecture du code : l'appariement par id est sain — base_by_id construit uniquement sur les cellules avec id ; cellule head sans id → repli positionnel (legacy) ; cellule head avec id frais → UNPAIRED (clean, pas de faux stale). Le cas use_ids mixte (base partiellement avec ids) est cohérent : une cellule head sans id mais dont la position a shifté retombe sur le repli positionnel — comportement documenté, acceptable pour les notebooks legacy. Sécurité : aucun secret/token dans le diff.

Verdict : fix de cause racine (pairing positionnel → pairing sémantique), tests ciblés qui couvrent le cas #14297 ET le cas anti-masquage. (contrainte token : COMMENT only)

[github-actions]

Bash Syntax Advisory — shebang / executable-bit warnings

See the Shebang + dry-run advisory job log for the per-file ::warning:: lines. Non-blocking.

[jsboige]

[COMMENT] Firsthand check sur head 3f6e4500a — worktree + unittest réels : 22/22 tests OK (dont les 3 nouveaux : test_insertion_with_ids_does_not_fabricate_stale_pair, test_shifted_cells_pair_by_id_after_conforming_insertion, test_id_pairing_still_flags_real_stale_output).

Cohérence avec l'issue #14297 :

• Le bug décrit (appariement positionnel → 3/3 STALE_OUTPUT sur PRs d'enrichissement) est adressé à la source : classify_cells() apparie par nbformat id quand la base en porte, cellule insérée (id frais) → UNPAIRED, cellule décalée → identité conservée.
• Fallback positionnel préservé pour notebooks legacy sans id — pas de régression sur la doc.
• Anti-régression présent : test_id_pairing_still_flags_real_stale_output prouve que le pairing par id ne masque PAS un vrai stale (même id, source changée, outputs identiques → STALE_OUTPUT).

Rien à redire. LGTM (contrainte token : COMMENT only).

[REVIEW] par Hermes — 1er passage sur ce SHA.