# Changelog — Picarones Tous les changements notables de ce projet sont documentés dans ce fichier. Le format suit [Keep a Changelog](https://keepachangelog.com/fr/1.0.0/). La numérotation de version suit [Semantic Versioning](https://semver.org/lang/fr/). Politique de versionning : voir [`docs/explanation/versioning.md`](docs/explanation/versioning.md). --- ## Note de repositionnement (2026-05-23) Le projet a été repositionné en **SemVer pré-1.0** à cette date. La release précédemment dénommée **« 2.0.0 »** (clôture du rewrite architectural en 8 couches, mai 2026) est désormais référencée comme **`0.9.0`** dans ce changelog. Justification : à la clôture du rewrite, le projet n'avait ni interface utilisateur finalisée, ni parité importeurs, ni rapport refondu — la dénomination « 2.0 » reflétait un cycle de refactor interne, pas une release publique mûre. La sortie de `1.0.0` deviendra un événement public marquant à la livraison de ces chantiers. Les sections historiques de ce fichier (et de la doc archive) qui citent « v2.0 » ou « v1.x » dans leur **prose** n'ont pas été réécrites : modifier le passé pour faire coïncider la terminologie avec le présent serait une réécriture d'historique trompeuse. Lis « v2.0 » dans ces sections comme « l'état du code à la clôture du rewrite, devenu `0.9.0` au repositionnement ». Seuls les **titres de version** (`## [X.Y.Z]`) ont été réalignés pour que les tags git et les releases PyPI futures restent cohérents avec le numéro courant. --- ## Roadmap vers 1.0.0 La sortie de `1.0.0` est conditionnée à la livraison de : 1. **Surface UI complète** — exposition de tous les champs du modèle `BenchmarkRunRequest`, parité fonctionnelle avec la CLI (`compare`, `robustness`, `history`). 2. **Parité importeurs corpus** — IIIF, Gallica, eScriptorium accessibles depuis l'UI web. 3. **Refonte rapport HTML** — IA 4 onglets (Overview / Engines / Documents / Crosses). Les versions intermédiaires `0.10.0`, `0.11.0`, etc. publient des jalons techniques au fil du chantier. --- ## Lecture chronologique du fichier Les **trois sections `[Unreleased]`** ci-dessous (« Migration Option B », « Audit code-quality », « Chantier post-rewrite ») documentent des chantiers parallèles réalisés **pendant la fenêtre du rewrite** (mai 2026), dont l'aboutissement est consigné dans la section ``[0.9.0] — Legacy retirement complete`` plus bas. Elles ont été préservées sous forme `[Unreleased]` pour refléter l'état où chaque branche a été rédigée — chaque branche était alors un chantier distinct avant que le rewrite ne les absorbe toutes. À partir de la release `0.9.0`, le CHANGELOG suit Keep-a-Changelog strict : **une seule section `[Unreleased]` à la fois** au-dessus de la version courante. Ordre de lecture chronologique : 1. ``[0.9.0] — Legacy retirement complete (mai 2026)`` — aboutissement. 2. ``[Unreleased] — Migration Option B`` — sous-chantier intégré. 3. ``[Unreleased] — Audit code-quality`` — sous-chantier intégré. 4. ``[Unreleased] — Chantier post-rewrite`` — sous-chantier intégré. --- ## [Unreleased] — Retrait de `execution_mode` (mai 2026) Branche `claude/focused-turing-2eFHt`. ### Removed (breaking, surface adapter) - L'attribut de classe ``execution_mode`` est retiré de tous les adapters (``BaseOCRAdapter``, ``BaseLLMAdapter``, ``BaseModule``) ainsi que le type ``ExecutionMode`` (``picarones.pipeline.protocols``, ``picarones.domain.module_protocol``). Aucun consommateur n'en dépendait — l'attribut prétendait depuis longtemps influencer le pool d'exécution du ``CorpusRunner`` mais le runner est thread-only par conception et n'a jamais lu ce champ. - Le type ``ExecutionMode`` n'est plus ré-exporté par ``picarones.pipeline``. ### Changed (documentation) - ``picarones/pipeline/runner.py`` : la docstring assume désormais explicitement le choix thread-only. Tous les adapters supportés (OCR via binaire C, LLM/VLM via httpx, ML via PyTorch/TensorFlow) délèguent leur travail bloquant à du code natif qui relâche le GIL, donc un thread pool unique donne les performances attendues. - ``docs/reference/specification.md`` et ``docs/reference/api-stable.md`` réconciliés avec l'arborescence canonique 0.9.0. - ``README.md``, ``CLAUDE.md``, ``docs/developer/module-policy.md`` mis à jour. ### Added - ``tests/architecture/test_no_execution_mode_resurrection.py`` — bloque la réintroduction silencieuse de l'attribut. Le test pointe vers le rationale et l'historique git (commits ``047ab1b`` et ``cd67184``) en cas d'échec. ### Pourquoi L'attribut était un mensonge structurel. L'historique git portait une tentative de dispatch multi-pool (``MultiDomainCorpusRunner``, commit ``047ab1b``) qui a été suspendue (``cd67184``). Aucun adapter actuel n'est GIL-bound en pratique — chacun délègue à du C qui relâche le GIL. Retirer plutôt que documenter un attribut zombi : YAGNI. --- ## [Unreleased] — Chantier UI + refonte rapport XerOCR (mai 2026) Branche `claude/charming-ritchie-Z820A` — chantier 17 commits qui attaque les trois prérequis annoncés de `1.0.0` (surface UI complète, parité importeurs, refonte rapport). À mi-parcours : refonte rapport et importeurs livrés, surface UI partiellement étendue. ### Versioning — repositionnement SemVer pré-1.0 - ``0.9.0`` officialisé (auparavant la sortie « 2.0 » du rewrite a été renumérotée — cf. « Note de repositionnement » ci-dessus). - ``picarones/domain/_version_fallback.py`` introduit comme unique source de la version (``FALLBACK_VERSION = "0.9.0"``) — garde-fou par ``tests/architecture/test_single_version_source.py`` et ``test_no_hardcoded_version.py``. - Politique versioning documentée ([`docs/explanation/versioning.md`](docs/explanation/versioning.md)). ### Track APP — UI web (sprints S1-S4) - **S1 — Exposition de 6 toggles** de ``BenchmarkRunRequest`` dans l'UI (was : champs Pydantic ignorés par le frontend) : Wilcoxon, Friedman, bootstrap, robustness, NER extractor, historique opt-in. - **S2 — Importeurs IIIF + Gallica BnF** dans la vue Import : preview avant import, recherche SRU Gallica avec critères combinables, sélecteur de pages. - **S3 — Importeur eScriptorium** + catalogue HTR (Kraken/Calamari) : endpoint POST avec token API non loggé, validation HTTPS. - **S4 — Vue Historique longitudinal** : SQLite ``BenchmarkHistory``, sparklines SVG vanilla, table filtrable, détection des régressions via API REST dédiée. ### Track REPORT — refonte rapport HTML XerOCR (sprints S5-S12) - **S5a — Fondation visuelle XerOCR** : ``_design_tokens.css`` partagé avec l'app (palette warm paper + halftone Xerox Star + IBM Plex + Bricolage Grotesque + accents oklch ``fern/slate/clay/ butter``), guard-rail ``test_xerocr_tokens.py`` qui vérifie la parité tokens app↔rapport (42 assertions). - **S5b — Squelette nouvelle IA 4 vues + routeur hash** : ``_routing.js`` (vues XerOCR + sous-onglets ``engines/{table, stability, diagnostics}`` + deeplinks ``#`` + roving tabindex + navigation clavier ←/→/Home/End). - **S6 — Vue Overview** : hero stats + corpus card + ranking synthèse + narrative + diagramme de différence critique. - **S7 — Vue Engines/Tableau** : tableau de référence avec super-headers groupés par catégorie sémantique (clay/slate/ butter/fern), badges A→E (lettres + accents cycliques), mini-barres CSS, tri client-side. - **S8 — Vue Engines/Stabilité** : composite multirun + longitudinal + baseline + robustness_projection avec empty state pédagogique (2 prérequis listés). - **S9 — Vue Engines/Diagnostics** : 7 sections (levers, taxonomy, calibration, philological, NER, over-normalization, numerical_sequences), bloc Sur-normalisation lexicale dédié. - **S10 — Vue Documents** : galerie avec aperçus de strate synthétiques CSS (presse / imprimé / manuscrit / défaut), filtres par chip, drill-in délégué à la vue legacy, branchement des « lignes les plus problématiques » globales en bas. - **S11 — Vue Croisements** : inter-moteurs (divergence + oracle gap) + 4 scatters SVG vanilla (CER × Coût · CER × Gini · Ancrage × Longueur · CER × Durée, accents butter/slate/clay/fern) + spécialisation + comparaison taxonomique. - **S11b — Retrait wrapper ``
`` legacy** : passage à un container neutre ``legacy-views-container``, drill-in préservé, deeplinks legacy ``#ranking/#gallery/...`` préservés. - **S12 — Compare 2 runs + footer manifest + a11y polish** : comparaison de runs client-side (FileReader → delta CER par moteur → bandeau sticky avec régressions/améliorations, 0 appel réseau), footer manifest 3 zones (brand · manifest · actions), ``aria-current="page"`` + roving tabindex + focus rings visibles. ### Sprint S13 — Audit institutionnel + corrections critiques Audit à 4 angles (backend / JS+CSS / renderers Python / i18n+ tests+runtime) — 59 issues identifiées (12 critiques + 29 majeures + 18 mineures). Corrections appliquées par phases : - **Phase 1 — 10 critiques UX/i18n/cohérence** : 11 clés ``data-i18n`` manquantes ajoutées (``tab_*``, ``overview_*``, ``engines_*``, ``engines_sub_*``) ; 4 eyebrows + 5 aria-labels hardcodés FR migrés vers ``data-i18n-attr-aria-label`` ; 4 ``

`` regroupés en 1 seul (header) + 4 ``

`` (vues) ; ``engines-hero-stats`` peuplé (3 stats moteurs/pipelines/ métriques) ; ``_normalize_strate`` étendu à 20 termes paléographiques (gothique/humanistique/cursive/caroline/onciale/ bâtarde/textura/rotunda/fraktur/anglicana/secretary/chancery…) ; ``_switchView`` ne casse plus la nav XerOCR au drill-in ; Overview ↔ Documents lisent désormais la même source pour les strates ; hero scatter counter aligné sur ``isinstance`` ; modèles Anthropic fallback corrigés (modèles inventés retirés) ; triple duplication ``_ENGINE_ACCENTS`` factorisée dans ``picarones/reports/_helpers/engine_badges.py`` ; ``esc()`` legacy échappe désormais l'apostrophe (XSS via ``onclick='...'``) ; NORM par défaut affiche ``—`` au lieu de ``"nfc"`` fabriqué. - **Phase 2 — sécurité S2/S3 (C1 + M3)** : nouveau helper ``_import_guards.py`` qui applique ``state.enforce_rate_limit`` systématiquement sur ``iiif/gallica/escriptorium`` ; en mode public, plafonne ``max_resolution`` à 2048 px et refuse ``pages="all"`` ; nouveau ``_RevalidatingRedirectHandler`` dans ``_http.py`` qui re-valide chaque redirect HTTP (anti-SSRF post-redirect, parade AWS metadata). - **Phase 3 — polish + tests** : ``BenchmarkHistory`` passe en WAL mode + retry 30s (concurrence robuste) ; ``_compare.js`` ajoute MAX_BYTES 50 Mo + `Number.isFinite` (anti-NaN) + ``label_other`` dead code retiré ; renderers ``data-value`` échappés ; ``name=None`` → ``"—"`` au lieu de ``"None"`` ; ``worst_lines`` utilise ``

`` sémantique ; ``oklch()`` reçoit fallbacks ``#hex`` (Chrome <111 / Firefox <113 / Safari <15.4) ; ``test_renderer_exception_logged_not_raised`` teste effectivement le log via ``caplog`` ; fichier sprint-nommé renommé ; ``tests/reports/conftest.py`` centralise le fixture ``demo_html`` scope session. DoD : - 5560+ tests passent, 0 failed. - ``ruff check`` propre. - 4 audits indépendants : verdict « niveau institutionnel atteint » sur la majorité des dimensions ; reste 18 mineures documentées (dette technique). ### Audit XerOCR-2 — 9 phases de remédiation (mai 2026) Second tour d'audit après S13. Chaque phase isole un thème, mesure son impact via tests, et verrouille le résultat (les tests deviennent les contrats anti-régression). Cibles attaquées : bugs backend → frontend non exploités, qualité du rendu, fluidité, éléments graphiques, et code legacy dormant. - **Phase 1 — Reproductibilité scientifique** : - ``engine_config`` (modèle / température / prompt) propagé de ``EngineReport`` vers ``engines_summary`` puis affiché en ``
`` sous le nom de chaque moteur dans le tableau Engines — sans cela l'utilisateur ne voyait pas avec quels paramètres un CER avait été obtenu, contournant la reproductibilité. - 2 nouvelles colonnes ``μCER`` / ``μWER`` (métriques micro canoniques, indispensables pour les corpus déséquilibrés) réintroduites dans le tableau Engines + super-headers « ERREUR · CARACTÈRE/MOT » étendus. - ``overview.py:_resolve_normalization_label`` lisait ``snapshots.normalization_profile`` qui n'est jamais produit ; clé canonique ``snapshots.normalization`` rétablie — le snapshot autoritatif n'était plus silencieusement ignoré avec fallback systématique sur ``meta.metadata``. - **Phase 2 — Vue Stabilité fonctionnelle depuis SQLite history** : - Nouveau module ``picarones/reports/html/data/history.py`` (306 LOC) qui pont la SQLite ``BenchmarkHistory`` vers ``report_data`` — alimente ``longitudinal`` + ``baseline_difficulty`` + ``baseline_comparisons`` (consommé par le détecteur narratif ``engine_off_baseline``) + ``longitudinal_trends`` (alias consommé par ``regression_in_history``). - ``ReportGenerator`` accepte ``history=`` ou ``history_db_path=`` (défaut env var ``PICARONES_HISTORY_DB`` puis ``~/.picarones/history.db``). - Empty state composite Stabilité refactoré : retourne ``""`` quand les 4 sources internes sont vides, exposé séparément via ``build_stability_empty_state_html``. Le template arbitre : empty state UNIQUEMENT si composite + Wilcoxon + CER-dist sont tous silencieux — sinon le message « pas de données » contredisait visuellement les tests statistiques effectifs rendus juste en dessous. - **Phase 3 — taxonomy_comparison + cohérence scatter Crosses** : - Le composite Crosses lisait ``report_data["taxonomy_comparison"]`` qui n'était jamais produit — le bloc « comparaison taxonomique leader vs runner-up » apparaissait silencieusement vide. Nouveau ``compute_taxonomy_comparison_section`` dans ``data/extra_metrics.py``. - Hero stat Crosses comptait les scatters avec critère ``>= 2`` points mais ``_build_cer_cost_scatter`` rendait dès ``>= 1`` : hero disait « 0 scatters » mais un scatter dégénéré avec 1 point s'affichait quand même. Alignement strict ``isinstance + >= 2`` partout. - **Phase 4 — Galerie Documents + SVG aspectRatio** : - Badge difficulté intrinsèque (Facile / Modéré / Difficile / Très difficile, seuils 0.25 / 0.50 / 0.75 sur ``difficulty_score``) désormais affiché sur chaque carte de la galerie — le score était calculé par ``annotate_documents_with_difficulty`` mais jamais rendu. Couleur Okabe-Ito (colorblind-friendly). - Empty state Documents promu pédagogique : titre + body + 3 bullets (corpus, ground truth, images) — pattern aligné sur Stability / Diagnostics. - ``preserveAspectRatio="xMidYMid meet"`` ajouté aux 4 SVG entry points (helper ``svg_open`` + calibration + pipeline_dag + crosses scatters) — sans cet attribut, ``height:auto`` sur écran étroit écrasait verticalement les charts. - **Phase 5 — Retrait de 310 LOC de JS dormant** : - 6 fonctions Chart.js (``buildCerHistogram``, ``buildRadar``, ``buildVennDiagram``, ``buildWilcoxonTable``, ``buildGiniCerScatter``, ``buildRatioAnchorScatter``) ciblaient des canvas migrés vers SVG côté serveur en S7-S11. Les fonctions persistaient (parsed + JIT-compilées à chaque ouverture de rapport) grâce au try/catch d'orchestration de ``buildCharts()`` qui les laissait échouer silencieusement. ``_app.js`` : 2880 → 2570 LOC (–10,8 %). - 2 clés i18n orphelines retirées (``no_anchor_data``, ``no_gini``) — utilisées uniquement par les fonctions supprimées. - **Phase 6 — A11y clavier Overview + i18n normalization** : - Lignes ranking Overview avaient ``role="link" tabindex="0"`` sans gestionnaire keydown — inactivables au clavier alors qu'annoncées comme links. ``onkeydown`` ajouté pour Enter + Espace avec ``preventDefault``. - Fallback ``"(par défaut)"`` du label normalization devient i18n-aware via ``labels["overview_normalization_default"]``. - **Phase 7 — Couleurs scatters cohérentes + a11y Pareto + responsive** : - ``_build_scatter_svg`` attribuait la couleur des cercles via ``enumerate(cleaned)`` — index dans le tableau de points, pas rang du moteur dans le ranking CER. Le leader pouvait apparaître jaune dans Overview et vert dans le scatter Crosses selon l'ordre d'arrivée de ses données. Helper ``_engine_rank_map(report_data)`` thread le rang depuis ``report_data["ranking"]`` jusqu'à l'attribution de couleur — cohérence inter-tabs verrouillée. - Toggles Pareto (cost / speed / co2) gagnent ``aria-pressed`` + ``role="group"`` sur le toolbar — WCAG 2.1 AA fix (4.1.2 Name, Role, Value). ``setParetoAxis`` synchronise ``aria-pressed`` en plus de la classe CSS ``.active``. - Premier bloc ``@media (max-width: 600px)`` : hero stats en colonne, table Engines fluide, galerie Documents 140px min, scatters Crosses 1 colonne, bandeau compare wrap. - **Phase 8 — Pareto pipelines distincts + axes vides désactivés** : - Pipelines OCR+LLM rendaient ``pointStyle: 'circle'`` comme les moteurs natifs sur le Pareto — indistinguables visuellement. ``pointStyle: 'triangle'`` pour les pipelines (convention reprise des anciens scatters SVG retirés en Phase 5) + tooltip enrichi ``[pipeline]``. - ``_initParetoToggleAvailability()`` invoqué au boot désactive les toggles dont l'axe (speed / co2) n'a pas de données dans ``DATA.pareto`` — empêche un clic qui ouvrirait un canvas vide « Données insuffisantes ». - **Phase 9 — Image CLS + Escape compare + corpus mismatch** : - ```` Documents gallery sans ``width``/``height`` → CLS au premier paint ; sans ``onerror`` → icône « image broken » sur 404. Ajout des 3 attributs (width="200" height="267" pour aspect-ratio 3/4 + onerror display:none). - Bandeau compare non fermable au clavier — nouveau helper ``_wireBannerDismiss`` câble click + Escape avec auto-désinscription via flag ``_disposed``. - ``_detectCorpusMismatch`` émet un préfixe ⚠ + chip ``.xer-compare-warning`` quand les 2 runs comparés sont sur des corpus différents — l'utilisateur lit alors les deltas avec l'œil critique requis (mais peut comparer cross-corpus volontairement, la comparaison n'est pas bloquée). - Docstring de ``engine_badges.py`` récrite avec contrat explicite « ``idx`` = rang dans ``report_data["ranking"]`` (CER ascendant) » + warnings anti-patterns (ne PAS passer ``enumerate(engines)``, position alphabétique, ou tri utilisateur). Garde-fou contre la réintroduction en boucle du bug Phase 7 A1. DoD du chantier (9 phases) : - 5636 tests passent, 0 failed (vs 5560 avant — 76 nouveaux tests qui verrouillent les contrats anti-régression). - 310 LOC de JS dormant supprimées (``_app.js``). - 4 nouveaux modules / helpers (``data/history.py``, ``compute_taxonomy_comparison_section``, ``_engine_rank_map``, ``_difficulty_badge_html``, ``_wireBannerDismiss``). - Parité i18n FR ↔ EN maintenue (634 clés chacun). - ``ruff check`` propre sur tous les commits. ### Audit XerOCR-2bis — re-audit adversarial + Phase 16+ (mai 2026) Un re-audit adversarial post-Phase 15 a remonté 24 findings (1 CRITICAL, 11 HIGH, 8 MED, 4 LOW) qui ont prouvé que certains "fixes" des Phases 1-15 étaient incomplets ou faux. Les phases suivantes traitent ces findings par paquets cohérents avec preuve anti-theater (chaque test ajouté doit échouer sans le fix correspondant). - **Phase 16 — Bugs locaux urgents** : - **[1.1]** ``_initParetoToggleAvailability`` (``_app.js``) hardcodait ``if (axis === 'cost') return;`` — laissait le toggle cost cliquable même sans données pricing. Branche spéciale supprimée, traitement uniforme des 3 axes. - **[1.2]** ``_wireBannerDismiss`` (``_compare.js``) accumulait des handlers ``keydown`` sur ``document`` à chaque comparaison successive (le flag ``_disposed`` ne désinscrivait l'ancien handler qu'au prochain keydown — jamais si l'utilisateur ne tapait plus). Singleton module-level ``_currentKeyHandler`` qui désinscrit explicitement avant d'attacher un nouveau listener. - **[1.4]** ``_open_history`` (``data/history.py``) ouvrait une connexion SQLite sans jamais la fermer. Pattern batch (génération de N rapports) accumulait N handles ouverts sur le même ``.db`` jusqu'au GC + verrouillait le fichier sous Windows. Refactor en ``(history, owned)`` tuple — ``build_history_sections`` ferme la connexion en ``finally`` UNIQUEMENT quand elle l'a ouverte elle-même (préserve les fixtures partagées des tests). - **[5.1]** Seuils difficulté ``0.25 / 0.50 / 0.75`` dupliqués dans 3 fichiers (``evaluation/metrics/difficulty.py``, ``renderers/difficulty.py``, ``renderers/documents_gallery.py``). Nouveau ``difficulty_bucket(score) → str`` dans le module évaluation = source unique de vérité. ``difficulty_label``, ``difficulty_color`` et ``_difficulty_badge_html`` consomment désormais ce helper plutôt que ré-implémenter le bucketing. Changer un seuil ne demande plus 3 modifications parallèles. - **[5.2]** ``row.get("engine", "—")`` (``overview.py``) retournait ``None`` quand la clé existait avec valeur ``None``, ce qui affichait ``"None"`` littéral dans le ranking card. ``engines_table.py`` avait déjà documenté le piège ; pattern aligné ``row.get("engine") or "—"`` partout. - **Phase 16-bis — corrections post re-audit Phase 16** : Un re-audit ciblé sur les 3 commits Phase 16 a remonté 2 fixes incomplets (un partiel + un theater). Phase 16-bis les corrige réellement. - **[1.2] race condition résiduelle** : le singleton module-level ``_currentKeyHandler`` introduisait une fenêtre théorique où un keydown qui arrivait entre ``removeEventListener(old)`` et la réassignation pouvait lire la mauvaise valeur. Handler stocké désormais directement sur l'élément DOM ``banner._keyHandler`` — pas de partage entre instances, séquence strictement locale. - **[5.1] theater côté JavaScript** : la Phase 16 avait migré le bucketing difficulté côté Python (``difficulty_bucket`` comme source unique) mais avait oublié 3 copies du même bucketing dans ``_app.js`` (lignes 912-913, 969). Un changement de seuil Python aurait laissé le JS aux anciens seuils — drift silencieuse. Le dict document expose désormais ``difficulty_slug`` annoté par Python ; le JS le lit directement, ne calcule plus rien. Nouveau test pytest qui grep le JS pour interdire toute réintroduction de bucketing. - **Phase 17 — Tests theater retissés** : Le re-audit adversarial avait flaggé plusieurs tests Phase 1-15 comme « theater » : ils vérifiaient la présence de chaînes de caractères inertes (souvent dans du CSS inliné) plutôt que le comportement. Un test qui passe sous sabotage du code n'est pas un test, c'est une cérémonie. - **[2.1]** ``test_difficulty_badge_present_on_demo_cards`` cherchait ``"doc-card-difficulty"`` ; cette chaîne apparaît aussi dans la définition CSS ``.doc-card-difficulty {`` inlinée via ``{% include '_styles.css' %}``. Le test passait même si le renderer retournait ``""`` pour tous les docs (vérifié par sabotage temporaire). Pattern strict ```` inline. Trou critique du guard découvert --------------------------------- En écrivant le sabotage anti-theater pour [3.5], j'ai découvert que ``_find_isolated_hex`` strippait via regex TOUS les triple-quoted strings, y compris les string literals contenant du CSS. Conséquence : un hex isolé à l'intérieur de ``_INLINE_CSS = """..."""`` était invisible au guard — l'ancien test passait même sans aucune migration. Fix du guard ------------ ``_find_isolated_hex`` utilise désormais ``ast.parse`` pour identifier précisément les lignes qui appartiennent à des docstrings réels (module / fonction / classe). Les string literals assignés à une variable (cas ``_INLINE_CSS``) ne sont PAS masqués — leur contenu reste sous surveillance. Pour les fichiers non-Python (HTML, Jinja2), l'AST échoue et on retombe sur set vide — aucun strip particulier, tous les hex doivent passer le guard tel quel (cohérent avec le comportement attendu pour des templates). Migrations effectives --------------------- - **[3.5]** ``render.py:_INLINE_CSS`` : 20 hex inline (``#222``, ``#444``, ``#ccc``, ``#f4f4f4``, ``#888``, ``#fafafa``, ``#fff8e1``, ``#f9a825``, ``#555``, ``#777``) migrés vers ``var(--ink, ...)``, ``var(--g-700, ...)``, ``var(--g-200, ...)``, ``var(--g-50, ...)``, ``var(--g-500, ...)``, ``var(--paper, ...)``, ``var(--butter-soft, ...)``, ``var(--butter-deep, ...)``, ``var(--g-600, ...)``. - **Bonus** : ``comparison.py`` (CSS inline pour rapport de comparaison de runs) : 15 hex migrés vers la même palette warm paper + ``--fern`` / ``--clay`` / ``--fern-soft`` / ``--clay-soft`` / ``--fern-deep`` / ``--clay-deep``. Guard étendu : auto-discovery ``REPORTS_HTML_DIR.glob("*.py")`` ajoute les 5 modules top-level (``render.py``, ``generator.py``, ``snapshot.py``, ``section_registry.py``, ``comparison.py``) à la couverture. ``_EXEMPTED_TOP_LEVEL_PY`` ne contient que ``__init__.py``. Preuve anti-theater ------------------- Sabotage de ``var(--g-200, #ccc)`` → ``#ccc`` autonome à l'intérieur de ``_INLINE_CSS`` dans ``render.py``. Avant le fix du guard : test passait silencieusement (theater). Après : test échoue sur ``ligne 142 : #ccc`` avec assertion exacte. Restauration → 59/59 verts (37 renderers + 17 templates + 5 top-level py). - **Phase 18c — hex → tokens dans ``_styles.css``** : Troisième morceau du chantier migration CSS, le plus volumineux jusqu'ici : **90 hex isolés** dans ``_styles.css`` migrés vers des fallbacks tokenisés. Trois durcissements du guard découverts en chemin -------------------------------------------------- Comme en Phase 18b, le travail de migration a exposé des faiblesses du guard de Phase 17-18b qu'il a fallu corriger : 1. **Définitions de tokens hors ``:root``** : les blocs ``body.palette-classic`` et ``body:not(.palette-classic)`` définissent ``--palette-good/warning/bad`` avec les hex Okabe-Ito. Ces hex sont des sources de palette, pas des couleurs autonomes. Guard accepte désormais le pattern ``--token-name:`` immédiatement avant un hex (cas (b) du filtrage). 2. **Commentaires CSS ``/* ... */``** : peuvent contenir des hex explicatifs (``/* #EBE8E0 warm paper */``) qui ne sont pas des couleurs actives. Guard strippe désormais les commentaires CSS en passe préalable (en préservant la numérotation de ligne). 3. **Data URLs ``data:image/svg+xml``** : leurs ``%23abc123`` URL-encoded contiennent des hex légitimes (contenu d'image SVG inliné, pas une couleur CSS). Guard ignore les lignes contenant ``data:image/``. Sans ces durcissements, ma migration aurait été en partie ``theater`` : les hex dans les blocs de tokens palette alternative seraient flaggés comme erreurs, et les hex dans les commentaires explicatifs aussi. Migrations effectives (finding [3.3]) -------------------------------------- Inventaire pré-migration : 90 hex isolés en 42 codes uniques. - **Couleurs warm paper** : ``#fff`` → ``var(--paper, #fff)``, ``#16a34a`` → ``var(--fern, #16a34a)``, ``#dc2626`` → ``var(--clay-deep, #dc2626)``, etc. (~22 mappings sur les hex les plus fréquents). - **Greys neutres** : ``#f8fafc`` → ``var(--g-50, ...)``, ``#f1f5f9`` → ``var(--g-100, ...)``, ``#94a3b8`` → ``var(--g-300, ...)``, etc. - **Nouvelles palettes catégoriques** ajoutées à ``_design_tokens.css`` pour 18 hex qui ne mappaient pas aux tokens existants : - ``--accent-info`` (blue : header info OCR side-by-side). - ``--accent-ocr`` (cyan : chip étape OCR). - ``--accent-llm`` (violet : chip étape LLM, correction). - ``--accent-halluc`` (pink : tag hallucination). Chacun avec variantes ``-soft`` / ``-edge`` / ``-deep`` / ``-mid`` selon les usages observés. Ces accents sont **distincts** de la palette qualité ``--fern / --slate / --clay / --butter`` : ils servent à différencier des CATÉGORIES (étape, type de contenu) pas un niveau de qualité. Couverture du guard étendue à ``*.css`` ---------------------------------------- ``_discover_templates`` glob désormais aussi ``*.css``. ``_styles.css`` (~2600 LOC) et ``_design_tokens.css`` (~150 LOC) couverts par le guard. Preuve anti-theater ------------------- Sabotage ``color: var(--fern, #16a34a)`` → ``color: #16a34a`` ligne 1561 d'une vraie règle CSS active. Test échoue avec assertion exacte (``ligne 1561 : #16a34a``). Restauration → 61/61 verts (37 renderers + 17 templates HTML + 2 CSS + 5 top-level py). Note de risque visuel --------------------- Le test passe sur la conformité hex mais ne garantit PAS l'absence de régression visuelle. Les ``var(--xxx, #hex)`` utilisent le token CSS si supporté (browsers ≥ 2017), sinon fallback hex. Vérification visuelle recommandée via ``picarones demo --output /tmp/test.html``. Sous-phase restante Phase 18 : **18d** ``_app.js`` PALETTE + ``engineColor()`` ranking ordering — TRÈS RISQUÉ (intestable sans browser). ### Phase 19-23 — Refonte IA 4 onglets XerOCR + retrait Analyses (mai 2026) Le chantier S5-S12 (Track REPORT plus haut) avait posé l'IA 4 vues mais ~8 charts Chart.js et la matrice de corrélation interactive vivaient encore dans un 5e onglet temporaire « Analyses ». Phase 19-23 termine la migration, supprime l'onglet, et nettoie 225 LOC de dead code post-Étage 4. - **Phase 19** — Nav bar refondue : padding ``_styles.css`` symétrique ``6px 14px`` (était ``6px 10px 6px 18px``), 3 boutons d'action enveloppés dans ``
`` avec gap interne propre. 9 tests structurels + double sabotage anti-theater. - **Phase 20** — PALETTE XerOCR + ``engineColor()`` par rang CER : ``_app.js`` perd la PALETTE Tailwind statique (10 hex vifs), gagne un ``_CHART_PALETTE`` (5 tokens) lu via ``getComputedStyle`` au boot ; ``_ENGINE_RANK_MAP`` construit depuis ``DATA.ranking`` (miroir JS de ``_engine_rank_map()`` Python). 11 callsites migrés (index → nom de moteur). 15 tests + 3 sabotages. - **Phase 21A** — Engines/Tableau : dispatch ``chart-duration`` + ``chart-bootstrap-ci`` + ``economics_view_html`` depuis view_analyses vers ``engines_table.html``. Trigger ``buildCharts()`` étendu aux vues à charts. Nouvelle clé i18n ``h_economics`` (parité FR/EN). - **Phase 21B** — Engines/Diagnostics : dispatch ``chart-taxonomy`` + ``chart-reliability`` + ``error-clusters-container`` + 6 sections HTML legacy (``readability_html``, ``advanced_taxonomy_view_html``, ``diagnostics_view_html``, ``rare_token_recall_html``, ``taxonomy_cooccurrence_html``, ``taxonomy_intra_doc_html``). 10 tests + 2 sabotages. - **Phase 21C** — Documents + Crosses : dispatch ``chart-cer-doc`` vers documents.html ; ``chart-quality-cer`` + ``pareto-chart`` (avec toolbar 3 axes + assumptions details) + ``marginal_cost_html`` vers crosses.html. 19 tests + 3 sabotages. Wrapper Pareto passe de ``chart-card pareto-card`` à ``card xer-chart-card pareto-card`` (convention XerOCR). - **Phase 21D** — Cleanup JS corr-matrix mort : suppression de ``initCorrelationMatrix``, ``renderCorrelationMatrix``, ``corrColor`` (dupliquaient le renderer Python ``build_correlation_matrix_html`` + 10 hex CSS-in-JS hors palette). Clé i18n orpheline ``corr_engine_label`` retirée (parité 635/635). 7 tests + 3 sabotages. - **Phase 22+23** — Suppression onglet Analyses + ``view_results`` en ``
`` : ``view_analyses.html`` supprimé, bouton nav retiré, ``XER_VIEWS`` nettoyé. ``view_results_html`` (projections EvaluationView : TextView, AltoView) intégré en ``
`` repliable au bas de ``engines_diagnostics.html``. Whitespace Jinja2 ``{%- if %}`` introduit pour éviter l'accumulation de newlines en conditionnels chaînés (régression du garde-fou cosmétique). 13 tests + 3 sabotages. Phases combinées en un seul commit pour éviter l'état intermédiaire où ``view_results_html`` serait computed mais non rendu. 5779 tests passants après Phase 22+23. ### Audit X1-X4 — remédiation post-Phase 23 (mai 2026) Audit adversarial multi-agents (5 angles indépendants) post-Phase 19-23 a remonté 4 catégories de findings, traités en 4 commits atomiques avec discipline test-first + sabotage anti-theater. - **X1** — ``engineColor()`` self-healing contre race condition deeplink : bug runtime non détecté en Phase 20. ``_routing.js`` (chargé avant ``_app.js``) enregistre son handler ``DOMContentLoaded`` qui s'exécute AVANT celui de ``_app.js``. Sur deeplink ``#engines``/``#documents``/``#crosses``, ``buildCharts()`` se déclenche → ``engineColor()`` lit ``_CHART_PALETTE`` encore vide → fallback fern hardcodé retourné pour TOUS les moteurs (charts monochromes verts uniformes). Fix : pattern self-healing, ``engineColor()`` appelle ``_ensureChartPaletteInitialized()`` et ``_ensureEngineRankMapInitialized()`` (idempotentes) en première instruction. Fallback hex retiré (l'invariant tient toujours via lazy init). 7 nouveaux tests TestEngineColorLazyInit + TestBootOrder remplacé par TestBootWarmup (2 tests — les anciens étaient devenus theater post-refactor, passaient en matchant la définition de fonction au top du fichier). 5 sabotages anti-theater validés. - **X2** — Durcissement de 7 tests theater : 7 assertions modifiées (initialement ``or "X" in html.lower()`` qui matchaient trivialement — « wilcoxon » : 129 occurrences dans HTML, « correlation » : 21, « venn » : 16, « Gini » : 33, « Ancrage » : 17, ``VLM`` : multiple) remplacées par des ancres structurelles uniques (``id="..."``, ``class="..."``, ``aria-label="..."``). Découverte : un ``replace(..., ..., 1)`` faible peut faire passer un sabotage à tort si la chaîne apparaît plusieurs fois ; et les ``aria-label`` sont résolus via i18n au rendu, pas via le renderer Python. 6 sabotages anti-theater validés. - **X3** — Consolidation ``margin-top: 1.25rem`` inline : 20 occurrences répétées dans 5 templates retirées au profit d'une règle CSS unique ``.xer-chart-card``. Margin-collapse standard avec ``.card { margin-bottom: 1.25rem }`` garantit le spacing visuel identique (parents ``.view.active`` et ``.xer-subpane.active`` sont ``display: block``, collapse applique — verifié). Cas spécial Venn : ``border-left:3px solid var(--butter)`` préservé. 7 tests + 3 sabotages. Découverte : test-theater dans mon propre test initial (regex matchait un commentaire CSS qui mentionnait la propriété) corrigé via strip ``/* */`` et exigence du ``;`` final. - **X4** — Null check ``_switchView`` + retrait dead code Étage 4 : ``_switchView`` accédait ``getElementById(...).classList`` sans null check → crash sur hash invalide (``#characters``, ``#foo``). Fix : garde + fallback silencieux vers overview via ``window.showXerView`` + ``console.debug`` pour traçabilité. Retrait de 6 fonctions JS dormantes (``initCharView``, ``renderCharView``, ``renderConfusionHeatmap``, ``renderLigatureDetail``, ``renderTaxonomyDetail``, ``showConfusionExamples``), du ``let charViewBuilt``, de ``characters:'caract'`` dans tabMap, et du ``if (name === 'characters')``. ~225 LOC nettes retirées de ``_app.js``. Bonus : 6 hex hardcodés inline dans ``renderConfusionHeatmap`` retirés (dette CSS-in-JS qui aurait échappé au guard hex). 4 fonctions de test ajoutées (dont 1 paramétrée à 7 instances → 10 cas exécutés au total) + 3 sabotages. 5801 tests passants post-X4. Ruff propre. i18n parité 635/635. **Apprentissages méta de l'audit** : - Les sabotages doivent eux-mêmes être audités : un ``replace(..., 1)`` faible passe à tort, un test qui grep un commentaire CSS devient theater. - Les ancres de test doivent être structurelles (IDs uniques, classes spécifiques, combinaisons exactes), pas sémantiques (mots génériques comme « correlation » ou « wilcoxon » qui matchent du bruit dans le HTML). - Le pattern self-healing élimine les race conditions à la racine plutôt que de les masquer par un ordre d'exécution fragile. - Les claims de commit messages doivent être croisées contre le diff réel — drifts numériques mineurs des commits initiaux (X1 : 5 claim/7 réel ; X2 : 6 claim/7 réel ; X3 : 21 claim/20 réel ; X4 hex : 12 claim/6 réel) corrigés dans cette entrée CHANGELOG. ### Méta-audit Z1-Z3 — anti-theater systémique des tests (mai 2026) Audit adversarial post-Y4 (« consultant externe mandaté pour détruire ») a découvert que la discipline test-first + sabotage revendiquée tout au long de l'audit X-Y était elle-même **partiellement theater**. Mes sabotages remplaçaient ou supprimaient le code ; ils ne le commentaient JAMAIS, ni ne préservaient sa structure tout en cassant sa sémantique. Trois classes de theater systémique exposées : - **Z1 — Theater par commentaire (systémique, 14+ tests affectés)** : Les tests qui grep du source code (JS, CSS, HTML, Jinja2, Markdown) sans strip de commentaires sont trompés par un sabotage qui COMMENTE le code. La chaîne recherchée reste dans le fichier mais n'a aucun effet runtime. Mesuré : 14/14 tests palette/init passent en commentant le top de ``_app.js``. Fix : ``tests/_strip_helpers.py`` (helper centralisé pour 5 langages) + refactor de 7 fichiers de tests. 17 tests méta valident le helper lui-même. - **Z2 — Theater par sabotage qui préserve la structure** : Un sabotage qui PRÉSERVE les chaînes recherchées tout en BRISANT la sémantique runtime (early-return après guard d'idempotence, constante hardcodée pour le rank, init dans un ``if(false)``) passait à travers Z1. 3 sabotages distincts non détectés : - early-return réintroduisait silencieusement le bug X1 - ``const rank = 0`` faisait que engineColor retournait fern pour tous les moteurs - init dans ``if(false)`` rendait l'init unreachable Fix : 2 tests structurels plus stricts dans ``test_app_js_palette.py`` qui vérifient la SÉMANTIQUE post-guard (assignation effective à ``_CHART_PALETTE``, lookup de ``rank`` utilise ``engineName``). - **Z3 — Theater par decoy dans le HTML rendu** : les tests qui grep le HTML produit par ``picarones demo`` (fixtures ``html_s7``, ``html_report``) sont trompés par un decoy dans un commentaire HTML qui survit au rendu Jinja2 : ``

`` Le grep matche le decoy, le test passe, mais l'utilisateur ne voit pas le titre. Fix : strip ```` HTML avant le grep dans les 7 assertions X2 (Venn, Wilcoxon, error-clusters, correlation, Gini scatter, Anchor scatter, VLM badge). **Apprentissage méta** : - Mes sabotages anti-theater étaient eux-mêmes incomplets — il faut SYSTÉMATIQUEMENT tester 4 modes de defeat : (1) suppression, (2) commentaire, (3) préservation structurelle + bris sémantique, (4) decoy dans le rendu. - Les tests structurels (grep sur source) ont des LIMITES fondamentales — seuls les tests runtime via JS engine (jsdom, Playwright) garantissent la sémantique exécutoire. Décision pragmatique 0.9.x : défense multi-couches structurel (Z1+Z2+Z3) documentée comme tel, runtime opt-in à évaluer pour 1.0. **Audit runtime indépendant** (via Node + jsdom durant la session) : - ``engineColor()`` retourne des OKLCH valides pour les 5 engines du demo (vérifié par eval inside jsdom) - ``_switchView()`` robuste contre tous les edge cases testés : ``""``, ``null``, ``undefined``, ``"foo"``, ``""``, ``"../etc/passwd"`` → tous redirigent vers ``overview`` sans crash - ``engineColor()`` robuste contre prototype pollution (``__proto__``, ``constructor``, ``toString``) via ``Object.prototype.hasOwnProperty.call`` - Les 6 fonctions retirées en X4 (initCharView etc.) sont effectivement undefined sur window post-load 5 sabotages adversariaux finaux (3 Z1 + 3 Z2 + 2 Z3) tous détectés. --- ## [Unreleased] — Migration Option B vers RunOrchestrator (mai 2026) Branche `claude/test-alto-pipelines-qyFsL` — chantier de migration complète vers `RunOrchestrator` comme entry-point canonique pour lancer un benchmark, avec livrable métier ALTO documentaire. 20+ commits sur ~13 jours d'effort, 4830 → 4897 tests passants (+67). ### Nouveautés — valeur métier - **`picarones.RunOrchestrator`** exposé au niveau racine. Consomme un `RunSpec` Pydantic validé et expose 4 fichiers JSONL natifs (`run_manifest.json`, `pipeline_results.jsonl`, `artifacts_index.jsonl`, `view_results.jsonl`) en plus du `BenchmarkResult` legacy (via `spec.output_json`). - **`RunSpec` étendu** avec 7 nouveaux champs : `char_exclude`, `normalization_profile`, `partial_dir`, `entity_extractor`, `profile`, `output_json`, `timeout_seconds_per_doc`. Tous validés par Pydantic (`_validate_profile_is_known`, `_validate_entity_extractor_format`). - **3 vues canoniques natives** dans le `RunResult` : `text_final`, `alto_documentary`, `searchability`. Chacune produit ses propres `ViewResult` typés avec `metric_values`, `failed_metrics`, `projection_report`, `warnings`. - **TesseractAdapter expose ALTO natif** via le flag `expose_alto` (off par défaut, compat ascendante). Premier adapter du repo à produire un `Artifact ALTO_XML`. Valide structurellement la sortie avant promotion (résistance XML mal formé). - **AltoView étendu** : 7 métriques par défaut au lieu de 3. Les 4 nouvelles (`alto_text_cer/wer/mer/wil`) opèrent sur le texte plat extrait de l'ALTO via `extract_text_from_alto` — permettent de détecter une régression textuelle même quand la structure est préservée. - **Rapport HTML multi-vues** : nouvelle section `view-results-section` rendue par `picarones/reports/html/renderers/view_results.py`. Affiche un tableau `Métrique × engine` par vue avec moyennes, et liste explicitement les **pipelines OMIS** de chaque vue (critique pour AltoView : un OCR sans ALTO ne doit pas être omis silencieusement). Adaptive : section absente si `benchmark.view_results` vide (chemin legacy intact). - **`BenchmarkResult.view_results`** : nouveau champ optionnel `{view: {engine: {doc: {metric: value}}}}` peuplé par le converter depuis le `RunResult.document_results[*].view_results`. Consommé par le rapport HTML et accessible aux clients pour analyses ad-hoc. ### BREAKING — Retrait du legacy (Phase B3-final, migration nette) Suppression complète de l'entry point legacy et de ses modules helpers internes. Les call sites CLI/Web/tests ont été migrés vers le **pattern 3 étapes explicite** (Option 10 du chantier) : ```python # Pattern moderne — 3 étapes visibles, pas de shim caché args = prepare_preset_args(corpus, engines, workspace_dir=...) orch_result = RunOrchestrator(out).execute_preset(**dataclass_fields) result = run_result_to_benchmark_result(orch_result.run_result, ...) ``` - **`run_benchmark_via_service` supprimée** — utilisez `RunOrchestrator` + `prepare_preset_args` (Python) ou `RunOrchestrator.execute(RunSpec)` (YAML). - **Modules supprimés en Phase B3-final** (~1700 LOC nettes pour cette phase isolée ; la branche complète cumule aussi l'audit code-quality qui ajoute massivement — voir entrée suivante) : * `benchmark_runner` (entry point legacy) * `_benchmark_execution` (helper interne orchestration) * `_benchmark_orchestration` (run_benchmark_unified / run_benchmark_with_partial) * `legacy_runner_compat` (shim intermédiaire B3 introduit puis supprimé dans le même chantier — voir entrée Option 10) - **Tests d'invariance supprimés** — leur rôle (garde-fou pendant la migration) est rempli, la migration est terminée : * `tests/integration/test_migration_invariance.py` * `tests/integration/snapshots/migration_invariance.json` ### Modifié — Audit B3-final correctif (mai 2026) L'audit implacable de la branche post-migration a identifié 4 demi-chantiers critiques : les features livrées en B5/B6/B2 étaient implémentées en interne mais **inaccessibles aux utilisateurs CLI/Web**. Corrections appliquées : - **CLI** : 5 nouvelles options ajoutées à `picarones run` : * `--views VIEW1,VIEW2,…` (B6 multi-vues) * `--expose-alto` (B5 Tesseract ALTO XML) * `--char-exclude CHARS` (B2.5) * `--partial-dir PATH` (B2.3 resume) * `--entity-extractor DOTTED_PATH` (B2.4 NER) `_engine_from_name` propage `expose_alto` à Tesseract. - **Web** : `BenchmarkRunRequest` étendu avec `views: list[ViewName]`, `profile`, `partial_dir`, `entity_extractor`, `output_json`. `PipelineConfig.expose_alto` activable par concurrent. Le worker `run_benchmark_thread_v2` propage les nouveaux champs au pattern 3 étapes. - **Helper test** : `tests/_migration_helpers.run_via_orchestrator` reçoit un kwarg `views` (corrige la divergence test↔prod identifiée par l'audit — aucun test B4 ne couvrait précédemment le multi-vues via le helper). Impact utilisateur : ```bash picarones run -c ./corpus -e tesseract --expose-alto \ --views text_final,alto_documentary,searchability \ --profile standard ``` Génère désormais un rapport HTML avec 3 sections (TextView, AltoView, SearchView) + ALTO XML natif de Tesseract. La valeur métier C3 est enfin accessible aux utilisateurs. ### Modifié - **`picarones.interfaces.cli._workflows`** : 6 commandes (`run`, `diagnose`, `economics`, `edition`, `compare`, `robustness`) utilisent désormais un helper local `_run_orchestrator_for_cli` qui mutualise le pattern 3 étapes. Comportement utilisateur identique. - **`picarones.interfaces.web.benchmark_utils.run_benchmark_thread_v2`** : pattern 3 étapes inline. L'API REST `POST /api/benchmark/run` est inchangée pour les clients. - **`picarones.app.services.__init__`** expose désormais `PresetArgs`, `prepare_preset_args`, `run_result_to_benchmark_result` comme API publique. - **`TesseractAdapter.output_types`** : étendu de `{RAW_TEXT, CONFIDENCES}` à `{RAW_TEXT, CONFIDENCES, ALTO_XML}` (set maximal). Les pipelines existants restent inchangés tant que `expose_alto` n'est pas activé. - **`build_text_view` / `build_search_view`** : nouveau kwarg `char_exclude` propagé jusqu'au `DefaultEvaluationViewExecutor` qui filtre les caractères avant calcul des métriques. ### Migration utilisateur Cf. `docs/archive/2026-migration/option-b-user-guide.md` pour le mapping complet des paramètres legacy → `RunSpec`, 4 cas concrets (corpus mémoire, partial_dir resume, NER attach, cancellation), et calendrier de retrait phasé. ### Phases du chantier (référence interne) - **B0** préparation (snapshot d'invariance + squelette feature parity + inventaire tests) - **B1** `RunSpec` étendu (7 nouveaux champs + validators) - **B2** porting des 7 features dans `RunOrchestrator` (progress_callback, cancel_event, partial_dir, entity_extractor, char_exclude + normalization_profile, profile hooks, output_json) → **Checkpoint C1** - **B3** exports publics + `DeprecationWarning` + migration concrète des call sites CLI/Web via `legacy_runner_compat` → **Checkpoint C2** - **B4** migration des 6 fichiers de tests catégorie A (71 appels) - **B5** `TesseractAdapter.expose_alto` (premier adapter ALTO natif) - **B6** rapport HTML multi-vues + extension `DEFAULT_ALTO_METRICS` → **Checkpoint C3** (valeur métier livrée) - **B7** deprecation finale (bannières + CHANGELOG initial) - **B3-final** (Option 10) — migration nette : helper `prepare_preset_args` + pattern 3 étapes inline dans CLI/Web/tests, puis suppression complète du shim `legacy_runner_compat` et des 3 modules purement legacy. **-1700 LOC nettes**. --- ## [Unreleased] — Audit code-quality (mai 2026) Branche `claude/code-quality-audit-EeY0r` — audit implacable du repo suite à la migration v2.0, suivi de 12 sprints correctifs (Phases 0 à 12 du plan d'audit). ### BREAKING — ruptures API v2.0 Toutes ces ruptures sont **immédiates**, sans calendrier de dépréciation (règle de l'audit : « soit on supprime, soit on garde et on développe »). Migration directe documentée ci-dessous. - **`POST /api/benchmark/start` retiré** au profit de `POST /api/benchmark/run`. Le modèle Pydantic `BenchmarkRequest` (liste de moteurs plats) est remplacé par `BenchmarkRunRequest` (liste de `PipelineConfig`). Helpers associés supprimés : `_legacy_request_to_run_request`, `run_benchmark_thread` (v1 ; `run_benchmark_thread_v2` reste). Migration : ```python # avant (v1.x) POST /api/benchmark/start {"corpus_path": "...", "engines": ["tesseract", "pero_ocr"]} # après (v2.0) POST /api/benchmark/run { "corpus_path": "...", "competitors": [ {"name": "tesseract", "engine_name": "tesseract"}, {"name": "pero_ocr", "engine_name": "pero_ocr"}, ], } ``` - **`run_benchmark_via_service(..., max_workers=4)` retiré** — paramètre absorbé sans effet via `# noqa: ARG001`. Le rewrite passe par `CorpusRunner.max_in_flight` directement. - **`expand_legacy_keys()` retiré** de `picarones.domain.artifacts` — 0 caller en production. Le dict `LEGACY_VALUE_ALIASES` reste vivant pour le canonicalisation des manifests legacy. - **JSON `BenchmarkResult` pré-v2.0 plus relisibles** — le retrait de `expand_legacy_keys` interdit le round-trip depuis des sorties v1.x. Régénérer les benchmarks de référence. - **Paramètre `text_hint` retiré** de `picarones.evaluation.synthetic._make_placeholder_png` (était jamais lu). ### Added — features inachevées débloquées - **Agrégation sur-normalisation LLM corpus-wide** : `aggregate_over_normalization` câblée via `@register_corpus_aggregator(name="over_normalization", ...)` (profils `philological`, `diagnostics`, `full`). Le hook extrait depuis `DocumentResult.pipeline_metadata["over_normalization"]` et alimente `EngineReport.aggregated_over_normalization`. Round-trip JSON préservé. - **Journal de fallbacks importer end-to-end** : la chaîne `record_fallback → consume_fallback_log → BenchmarkResult.metadata → build_report_data → narrative.detect_importer_fallback` est désormais branchée. Un fallback HTR-United mode démo apparaît dans la synthèse narrative avec traçabilité (URL, raison). - **Profils de normalisation YAML versionnables** : - CLI : `picarones run --normalization-profile ` — accepte un identifiant builtin ou un fichier `.yaml` versionné dans git. - API : `POST /api/normalization/profiles/preview` — valide un YAML utilisateur et retourne le profil sérialisé (preview, pas de persistance). Limite 64 KiB côté Pydantic. - **`register_default_metrics()` exposée publiquement** — remplace le side-effect `import picarones.evaluation.metrics` opaque en tête de `picarones/__init__.py`. Idempotente (`sys.modules` cache). Auto-déclenchement préservé pour rétrocompat. - **`RunResult` accessible depuis `picarones.pipeline.run_result`** — déplacé de `app.results` (compat shim conservé) vers la couche 4 pour respecter l'orientation des couches (`reports/` ne peut plus importer depuis `app/`). ### Changed — architecture & lisibilité - **8 `__init__.py` de couche** : renumérotation `Cercle N` (incohérent, max 5, doublons) → `Couche N` (1 à 8, ordre du manifeste). - **`benchmark_runner.py`** : 1 700 → 1 584 LOC. Extractions : - `_benchmark_ner.py` (NER aggregation, ~100 LOC). - `_benchmark_persistence.py` (sérialisation JSON, ~15 LOC). Budget `test_file_budgets` resserré de 1 750 à 1 620. - **`robustness.py`** : 850 → 578 LOC. Suppression des 5 helpers pure-Python `_apply_*` et du stub `_degrade_pure_python` (Pillow est dep obligatoire, fallback sans valeur). - **`PipelineMode` unifié** : source unique `picarones.domain.pipeline_spec.PipelineMode`. Les 3 alias historiques (`OCRLLMMode`, `OCRLLMPipelineMode`, `PipelineMode`) deviennent des re-exports. - **Validation chemin web factorisée** : helpers `validated_user_path` / `validated_user_output_dir` dans `interfaces/web/_path_helpers.py` ; 2 routers migrés. - **eScriptorium anti-SSRF** : `_get`, `_post` et le téléchargement d'image utilisent désormais `validate_http_url` et `download_url` (cohérence avec IIIF/Gallica/HTR-United). - **Tesseract `lang` validation** : regex `^[a-zA-Z]{3,}(\+[a-zA-Z]{3,})*$` rejette les injections CLI (`fra --user-words /etc/passwd`). - **CI : sync compteurs bloquant** — nouveau job ``sync-counters`` exécute `scripts/gen_readme_tables.py --check`. - **CI : 7 nouveaux tests d'architecture** verrouillent les invariants pour bloquer la régression : - `test_no_zombie_skips.py` (interdit `pytest.skip` sur dep obligatoire). - `test_no_legacy_imports_in_rewrite.py` refondu — test actif contre la résurrection des paquets legacy supprimés (au lieu d'un `LEGACY_PACKAGES = ()` vacuement vrai). - `test_no_broad_pytest_raises.py` — refuse les `pytest.raises(Exception)` (ratchet, baseline 24). - `test_logger_prefix.py` — refuse les logs sans préfixe `[]` (ratchet, baseline 46). - `test_live_test_markers.py` — chaque fonction dans `tests/integration/live/` porte `@pytest.mark.live`. - `test_reports_layer_strict.py` — interdit les imports `reports/ → {adapters, app, interfaces}`. - `test_pipeline_mode_single_source.py` — refuse toute nouvelle redéfinition de `Literal["text_only", "text_and_image", "zero_shot"]`. - `test_api_stable_modules_exist.py` — chaque module cité dans `api-stable.md` doit s'importer. ### Removed - **`POST /api/benchmark/start`** + helpers (cf. BREAKING). - **`BenchmarkRequest`** modèle Pydantic v1 (cf. BREAKING). - **`max_workers`**, **`text_hint`** paramètres morts. - **`expand_legacy_keys()`** (cf. BREAKING). - **5 helpers `_apply_*`** + **`_degrade_pure_python`** dans robustness.py (~300 LOC). - **7 `pytest.skip("click non installé")`** zombies dans `tests/integration/test_chantier{4,5}.py` (click est dep obligatoire — skip vacuement vrai). - **4 modules fantômes** retirés de `docs/reference/api-stable.md` (`pipeline.legacy_runner`, `pipeline.legacy_pipeline_benchmark`, `pipeline.legacy_pipeline_comparison`, `evaluation.metrics.pipeline_spec_loader`). ### Fixed - **`app.py`** : entry point HuggingFace cassé (`picarones.web.app:app` → `picarones.interfaces.web.app:app`). - **8 `except: pass` silencieux** : tous remplacés par `logger.warning("[] ...")` ou `logger.debug(...)` selon criticité (friedman_nemenyi, image_quality, iiif, clustering, path_security, benchmark_runner, job_store, robustness). - **10 `pytest.raises(Exception)` trop larges** : précisés en `FrozenInstanceError` ou `pydantic.ValidationError`. - **README.md** : retrait du paragraphe « Legacy paths still present as shims » (faux depuis v2.0) ; `mypy picarones/core/` → `mypy picarones/domain/`. - **CLAUDE.md** : compteur tests synchronisé (4 700 → réel), auto-contradiction « 12 vs 9 skipped » résolue, 18 → 20 détecteurs, 22 → 28 renderers. - **Faux positifs bandit B608** documentés avec `# nosec` et commentaire de justification (sites SQL où les `fields` interpolés sont des littéraux internes, valeurs via `?`). - **eScriptorium** : urlretrieve sans validation → `download_url` avec anti-SSRF. ### Security - **SSRF résiduel eScriptorium** fermé (`_get`, `_post`, téléchargement images). - **Injection CLI Tesseract** bloquée (regex sur `lang`). - **Aucune CVE** introduite (pip-audit vert). ### Stats - **+158 nouveaux tests** (4 686 → 4 784 passing). Ruff propre, bandit propre (1 LOW résiduel inoffensif), 0 régression. - **12 nouveaux modules** créés (helpers extraits + tests d'invariant). - **~600 LOC mortes supprimées**. --- ## [Unreleased] — Chantier post-rewrite (mai 2026) Branche `claude/fix-module-rewiring-MHssX` — réconciliation des chemins UI / API / runner / JSON / rapport après audit révélant des options ignorées, moteurs annoncés sans backend, surfaces filesystem ouvertes et round-trip JSON appauvri. ### Added - **Adapters `KrakenAdapter` et `CalamariAdapter`** (couche 5) avec lazy imports. Auparavant annoncés par `/api/engines` mais sans factory branchée — benchmark web échouait silencieusement. - **Extras pyproject `[calamari]`** (`calamari-ocr>=2.0.0`) ; l'extra `[kraken]` préexistant pointe désormais sur un adapter réel. - **`BenchmarkResult.from_dict` / `from_json_object`** restaurent fidèlement toutes les analyses avancées (taxonomy, confusion_matrix, NER, calibration, philological, searchability, hallucination, numerical_sequence, readability) ; le rapport régénéré depuis JSON est désormais indistinguable du in-memory. - **`partial_store.compute_run_fingerprint` + `partial_path_for_engine`** : hash SHA-256 stable (engine_config + normalization_profile + char_exclude + corpus mtime/size + code_version) suffixé au nom du fichier partiel. Deux runs avec configs différentes ne se contaminent plus. - **Workflows CLI `diagnose`/`economics`/`edition`** génèrent désormais le rapport HTML automatiquement à côté du JSON (`--no-html` pour skipper). Les docstrings vendaient déjà les vues HTML correspondantes. - **UI** : boutons "💾 Sauvegarder config" / "📂 Charger config" dans l'écran benchmark (binding sur `/api/config/save` + `/api/config/load` qui existaient mais n'étaient appelés par personne). - **UI** : bandeau "Mode démo" sous le titre HTR-United quand le catalogue distant est inaccessible (champ `is_demo` exposé par le router). - **Tests** : `tests/security/test_phase1_post_rewrite_wiring.py` (~50 tests couvrant les 5 phases) + extensions de tests existants. ### Changed - **`HTRUnitedCatalogue`** : router utilise `from_remote(timeout=5)` avec fallback automatique sur démo (au lieu de `from_demo()` exclusif). Variable d'env `PICARONES_HTR_UNITED_OFFLINE=1` pour forcer démo (CI / déploiements offline). - **`upload_purge_task` (RGPD)** : démarrée par le lifespan FastAPI (auparavant définie mais jamais lancée). `JobStore.create_job` reçoit désormais un payload `{"corpus": req.corpus_path}` pour que la purge identifie les corpus actifs. - **`/api/benchmark/start`** : worker unifié — délègue à `run_benchmark_thread_v2` après conversion `BenchmarkRequest → BenchmarkRunRequest`. Marqué deprecated dans les logs ; un seul chemin à patcher. - **CLI `engines`** : source de vérité unique avec `adapters/ocr/factory._SUPPORTED`. Plus de hardcode local `[tesseract, pero_ocr]` qui divergeait du web. - **`ReportGenerator.from_json`** : délègue à `BenchmarkResult.from_json_object` (simplification + fidélité). ### Breaking Changes - **`CompetitorConfig` → `PipelineConfig`** (renommage de classe). - **`PipelineConfig.ocr_engine` → `engine_name`** : le field accepte aussi `corpus` (OCR pré-calculé) et des VLMs en zero-shot — le préfixe `ocr_` était trompeur. Les clients qui envoyaient `{"ocr_engine": "…"}` doivent migrer vers `{"engine_name": "…"}` (Pydantic v2 ignore silencieusement l'extra → benchmark refuse). - **`PipelineConfig.pipeline_mode`** typé `Literal["text_only", "text_and_image", "zero_shot"]`. Toute autre valeur (y compris les anciens alias `post_correction_text` / `post_correction_image`) est rejetée en 422 par Pydantic — fini le fallback silencieux vers `text_only` qui masquait les configs invalides. ### Security - **`output_dir` validé** (`validated_path` contre `compute_workspace_roots`) dans `api_htr_united_import` et `api_huggingface_import` — plus de path traversal écriture. - **`db_path` validé** dans `/api/history/regressions` — plus de lecture SQLite arbitraire. Pour pointer une base hors workspace, exporter `PICARONES_HISTORY_DB`. - **ZIP collision de basename** : `a/img.png` + `b/img.png` ne s'écrasent plus silencieusement — second renommé avec préfixe slug du dirname source. - **ZIP image extraite validée** : `validate_image_safe` (Pillow.verify, anti-bombe, limite taille) appelé sur chaque image lors de l'extraction — auparavant les images extraites passaient sans vérif (zip bomb jusqu'à 500 Mo brut). ### Fixed - Round-trip `BenchmarkResult.to_json` ↔ `from_json` préserve désormais l'intégralité des analyses (reproductibilité scientifique). - Partial store fingerprint évite la réutilisation illégale de résultats entre runs avec configs différentes. --- ## [0.9.0] — Legacy retirement complete (mai 2026) > Cette entrée porte le numéro de version dénommé **« 2.0.0 »** > jusqu'au 2026-05-23, repositionné en `0.9.0` dans le cadre de > l'alignement SemVer pré-1.0 (voir « Note de repositionnement » en > tête de fichier). Le contenu n'a pas été réécrit : la prose > mentionne « v2.0 » et « 1.x » telles qu'elles étaient employées à > l'époque. **Breaking changes** majeurs : suppression complète des paquets legacy. L'architecture canonique 8 couches (`domain → formats → evaluation → pipeline → adapters → app → reports → interfaces`) est la seule arborescence du code. Aucun shim, aucun `_legacy/`, aucun `legacy_*` subdir. ### Suppressions (toutes Sprints A-H, mai 2026) **Top-level** : - `picarones/core/` — Lots A-G : domain, formats, evaluation - `picarones/measurements/` — Lot D + E : evaluation/metrics, statistics - `picarones/engines/`, `picarones/modules/` — Lot E : adapters/legacy_* - `picarones/report/` — Lot F : reports/html (Sprint H.3 : `reports_v2/` → `reports/`) - `picarones/llm/`, `picarones/pipelines/`, `picarones/cli/`, `picarones/web/`, `picarones/extras/`, `picarones/fixtures.py` — Sprints F, G, H.1 **Adapters legacy** : - `picarones/adapters/legacy_engines/` (Sprint H.2.d) : `BaseOCREngine`, `EngineResult`, `LegacyOCREngineExecutor`, `engine_from_name`, et les 5 adapters Tesseract/Pero/Mistral OCR/Google Vision/Azure DI legacy. Remplacés par `picarones.adapters.ocr.*` (`BaseOCRAdapter` natif, factory `ocr_adapter_from_name`). - `picarones/adapters/legacy_pipelines/` (Sprint H.2.c) : `OCRLLMPipeline`, `PipelineMode`. Remplacés par `picarones.pipeline.llm_pipeline_config.OCRLLMPipelineConfig` + `picarones.pipeline.llm_pipeline_builder.make_ocr_llm_pipeline_spec`. - `picarones/adapters/legacy_modules/` (Sprint H.2.a) : `TextToAltoMonoRegion`. **Interfaces legacy** : - `picarones/interfaces/cli/_legacy/` + stubs canoniques inachevés `interfaces/cli/{run,report,import_corpus}.py` (Sprint H.4) : consolidé en `interfaces/cli/` (16+ commandes Click). - `picarones/interfaces/web/_legacy/` + stubs canoniques inachevés `interfaces/web/{__init__,app,security}.py` + `routers/`, `templates/`, `static/`, `i18n/` (Sprint H.4) : consolidé en `interfaces/web/` (FastAPI + UI Jinja2 + SSE benchmark + ZIP upload). ### Renames - `picarones/reports_v2/` → `picarones/reports/` (Sprint H.3). - `picarones/app/services/_legacy_runner_adapter.py` → `picarones/app/services/benchmark_runner.py` (Sprint H.4) : drop le préfixe `_legacy_` ; c'est l'entry point public des interfaces vers `BenchmarkService`. - `picarones/app/services/_legacy_partial_store.py` → `picarones/app/services/partial_store.py` (Sprint H.4). ### Features ajoutées (Sprints D) - `partial_dir` : reprise sur interruption (NDJSON per-engine, Sprint D.2.b) — un benchmark crashé peut reprendre sans perdre le travail déjà fait. - `entity_extractor` : NER attach post-bench (Sprint D.2.e) — metrics NER calculées + agrégées sur les documents avec GT `ENTITIES`. - `over_normalization` : détection automatique pour les pipelines OCR+LLM avec OCR amont (Sprint D.2.d). - `validate_profile()` au démarrage du benchmark (Sprint D.2.f) : un profil inconnu lève `ValueError` avant tout calcul. ### Architecture - `LEGACY_PACKAGES = ()` dans `tests/architecture/test_no_legacy_imports_in_rewrite.py` : plus aucun paquet legacy. - `test_legacy_canonical_parity.py` supprimé (Sprint H.5) — la table de parité est sans objet à v2.0. - `test_layer_imports_are_legal[layer-X]` passe pour toutes les couches. ### Migration depuis 1.x ```python # AVANT (1.x) from picarones.cli import cli from picarones.engines.tesseract import TesseractEngine from picarones.measurements.runner import run_benchmark from picarones.pipelines import OCRLLMPipeline, PipelineMode from picarones.report.generator import ReportGenerator # APRÈS (2.0) from picarones.interfaces.cli import cli from picarones.adapters.ocr.tesseract import TesseractAdapter from picarones.app.services.benchmark_runner import run_benchmark_via_service from picarones.pipeline.llm_pipeline_config import OCRLLMPipelineConfig from picarones.reports.html.generator import ReportGenerator ``` ### Statistiques - 4126 tests passing, 0 failed. - ~10 paquets legacy supprimés. - ~50000 LOC de legacy retirées. - Architecture 8 couches respectée (vérifiée par 4 tests architecturaux : layer_imports, no_legacy_imports, layer_dependencies, file_budgets). --- --- > **Historique pré-v2.0** : les versions antérieures à 2.0 (janvier 2025 → avril 2026) > sont archivées dans > [`docs/archive/changelog-pre-v2.md`](docs/archive/changelog-pre-v2.md).