fix(audit): 5 corrections suite à l'audit complet de mes derniers sprints

Trois agents Explore indépendants ont audité les commits ee86836
(invariants), 2d6c41d (helpers consolidés) et d641f6e/6724f94
(découpage generator.py). Cinq problèmes réels identifiés et
corrigés :

1. **CRITIQUE — test_module_coverage.py basé sur regex incomplète**
Le pattern regex ne capturait que `from picarones.measurements.X
import Y` et oubliait `from picarones.measurements import X`,
`from . import X`, `from picarones.measurements import (X, Y)`.
Conséquence : 3 faux positifs dans la baseline (alto_metrics,
builtin_metrics, reading_order — importés en __init__.py mais
classés comme test-only) ET 4 faux négatifs (error_absorption,
longitudinal, module_policy, reliability — détectés à tort comme
ayant un consommateur via des imports DANS DES DOCSTRINGS).

Refactor : remplacement de la regex par un parser AST qui
- reconnaît les 5 syntaxes d'import valides Python ;
- ignore correctement les chaînes / docstrings.
Helpers extraits : `_imports_target_module` (absolu) et
`_imports_target_relative` (depuis le package). Baseline
recalibrée : 12 → 13 modules réellement test-only.

2. **MAJEURE — asymétrie d'API dans build_pareto_section**
La fonction (a) prenait `engines_summary` en premier (les autres
`build_*` prenaient `benchmark`) et (b) mutait `engines_summary`
en place. Mutation cachée + signature inhomogène.

Refactor : split en deux fonctions au nom explicite :
- `attach_engine_costs(engines_summary, benchmark)` mute
(le verbe "attach" annonce la mutation) ;
- `build_pareto_section(engines_summary)` est pure et lit les
coûts déjà attachés.
L'orchestrateur appelle les deux dans l'ordre, documenté en
docstring de `build_report_data`.

3. **MINEURE — except Exception silencieux dans assets.py**
`encode_image_b64` retournait `""` sans logguer, en violation
de la règle CLAUDE.md "remplacer except: pass par
logger.warning". Ajout d'un `logger.warning()` avec contexte
(chemin de l'image + exception) — le rapport reste fonctionnel
mais l'absence d'image n'est plus invisible.

4. **MINEURE — tests NaN/Inf manquants dans render_helpers**
`color_traffic_light` n'avait aucun test pour valeurs spéciales
IEEE 754. Ajout de 3 tests :
- NaN → fonction ne crash pas, retourne hex valide ;
- +inf → clamp à scale_max → vert (high_is_good) ;
- -inf → clamp à 0 → rouge ;
- scale_min > scale_max → ne crash pas.

5. **MINEURE — documentation des 3 conventions de bornes**
render_helpers.py expose 3 fonctions de coloration avec 3
conventions différentes (scale_min/max, max_value, max_abs).
Section "Conventions de bornes" ajoutée dans la docstring de
module pour expliquer le pourquoi de chaque convention (lié à
la sémantique métier des cellules concernées) et le choix des
palettes (rouge/jaune/vert pour traffic, bleu/vert/orange
diverging pour daltonisme).

Suite : 3834 passed, 2 skipped (vs 3830 précédemment, +3 NaN/Inf
+ 1 ajustement). 1 échec pré-existant (test_readme_dual_lang).
ruff : All checks passed!

picarones/report/assets.py

@@ -43,13 +43,19 @@ def load_vendor_js(name: str) -> str:
 
 
 def encode_image_b64(image_path: str, max_width: int = 1200) -> str:
-    """Lit une image, la redimensionne si besoin, et retourne un data-URI base64."""
+    """Lit une image, la redimensionne si besoin, et retourne un data-URI base64.
+
+    Retourne ``""`` si l'image est introuvable ou si l'encodage
+    échoue (Pillow indisponible, format non géré, fichier corrompu).
+    Logue un avertissement dans ce dernier cas — le rapport reste
+    fonctionnel mais l'image manquera dans la galerie.
+    """
+    p = Path(image_path)
+    if not p.exists():
+        return ""
     try:
         from PIL import Image
 
-        p = Path(image_path)
-        if not p.exists():
-            return ""
         with Image.open(p) as img:
             if img.width > max_width:
                 ratio = max_width / img.width
@@ -64,7 +70,13 @@ def encode_image_b64(image_path: str, max_width: int = 1200) -> str:
             b64 = base64.b64encode(buf.getvalue()).decode("ascii")
             mime = "image/jpeg" if fmt == "JPEG" else "image/png"
             return f"data:{mime};base64,{b64}"
-    except Exception:  # noqa: BLE001 — fallback silencieux côté report
+    except Exception as exc:  # noqa: BLE001 — fallback gracieux + warning
+        logger.warning(
+            "[report] échec d'encodage base64 de l'image %s : %s — "
+            "le rapport ignorera cette image",
+            image_path,
+            exc,
+        )
         return ""
 
 

picarones/report/render_helpers.py

@@ -21,6 +21,29 @@ API
 - :func:`text_color_for_bg` — noir ou blanc selon la luminosité du fond.
 - :func:`build_grid_svg` — builder de heatmap SVG paramétré.
 
+Conventions de bornes
+---------------------
+Trois conventions de paramétrage cohabitent (par dessein, pas par
+maladresse) :
+
+- :func:`color_traffic_light` accepte ``scale_min`` + ``scale_max``
+  parce que les cellules concernées (CER, ECE, deficit) peuvent
+  démarrer à une borne basse non nulle (rang 1 = vert, ou
+  ``scale_min=0.30`` pour démarrer le dégradé à partir d'un seuil).
+- :func:`color_single_gradient` accepte ``max_value`` parce que ces
+  cellules (Jaccard, densité) sont toujours bornées en bas par 0 —
+  pas besoin de ``scale_min``.
+- :func:`color_diverging` accepte ``max_abs`` parce que ces cellules
+  (deltas signés) sont symétriques autour de 0 — la borne est la
+  même des deux côtés.
+
+Le choix des couleurs reflète la sémantique métier : traffic-light
+utilise rouge/jaune/vert (échelle universelle de qualité), diverging
+utilise bleu/vert/orange par défaut (vert au centre = neutre,
+extrémités opposées sémantiquement, et ces 3 teintes restent
+distinguables en daltonisme deutéranope contrairement au
+rouge/vert).
+
 Palette
 -------
 Les bornes RGB des dégradés traffic-light sont la moyenne des palettes

picarones/report/report_data/__init__.py

@@ -14,10 +14,14 @@ Ce sous-package éclate la construction en modules thématiques :
   reliability curves, Venn, error clusters, corrélations.
 - :mod:`scatter` — Sprint 10 : Gini vs CER, ratio vs anchor.
 - :mod:`pareto` — Sprint 19 : 3 fronts Pareto + métadonnées pricing.
+  Expose deux fonctions séparées : :func:`attach_engine_costs`
+  (mute) et :func:`build_pareto_section` (pure).
 
 L'API publique :func:`build_report_data` orchestre ces modules dans
-le bon ordre (les coûts du module Pareto enrichissent en place le
-``engines_summary`` produit par :mod:`engines`).
+le bon ordre. La séquence Pareto en deux temps
+(``attach_engine_costs`` → ``build_pareto_section``) rend la
+mutation explicite — les fonctions ``build_*`` du sous-package
+sont pures sauf ``attach_engine_costs`` dont le nom le dit.
 """
 
 from __future__ import annotations
@@ -32,7 +36,10 @@ from picarones.report.report_data.documents import (
     build_documents,
 )
 from picarones.report.report_data.engines import build_engines_summary
-from picarones.report.report_data.pareto import build_pareto_section
+from picarones.report.report_data.pareto import (
+    attach_engine_costs,
+    build_pareto_section,
+)
 from picarones.report.report_data.scatter import (
     build_gini_vs_cer,
     build_ratio_vs_anchor,
@@ -53,14 +60,21 @@ def build_report_data(
 ) -> dict:
     """Transforme un :class:`BenchmarkResult` en dict pour le rapport HTML.
 
-    L'ordre est important : :mod:`pareto` lit et enrichit en place
-    le ``engines_summary`` produit par :mod:`engines`.
+    Ordre critique :
+
+    1. Construire ``engines_summary`` (pur).
+    2. Construire ``documents`` puis annoter avec la difficulté (mute
+       ``documents``).
+    3. **Attacher** les coûts à ``engines_summary`` (mute, nom
+       explicite).
+    4. **Construire** le bloc Pareto (pure, lit les coûts attachés).
     """
     engines_summary = build_engines_summary(benchmark)
     documents = build_documents(benchmark, images_b64)
     annotate_documents_with_difficulty(benchmark, documents)
 
-    pareto_data = build_pareto_section(engines_summary, benchmark)
+    attach_engine_costs(engines_summary, benchmark)
+    pareto_data = build_pareto_section(engines_summary)
 
     return {
         "meta": {

picarones/report/report_data/pareto.py

@@ -6,11 +6,24 @@ Construit trois fronts Pareto avec des axes alternatifs :
 - ``speed`` — CER vs durée moyenne par page.
 - ``co2`` — CER vs empreinte carbone (g CO₂ / 1000 pages, expérimental).
 
-**Effet de bord** : :func:`build_pareto_section` enrichit en place
-le ``engines_summary`` reçu en argument avec les champs
-``mean_duration_seconds`` et ``cost`` (coût par 1000 pages + détail
-de pricing). Cette responsabilité partagée est documentée dans le
-module ``__init__.py`` du sous-package.
+API
+---
+Deux fonctions séparées pour rendre le contrat explicite :
+
+1. :func:`attach_engine_costs` — **mute en place** ``engines_summary``
+   en y ajoutant ``mean_duration_seconds`` et ``cost`` (extraits du
+   benchmark et de la table de pricing). Le nom dit clairement qu'il
+   y a mutation.
+2. :func:`build_pareto_section` — **fonction pure**, lit les coûts
+   déjà attachés à ``engines_summary``. Retourne le dict ``pareto``
+   prêt pour le template.
+
+L'orchestrateur (``__init__.py``) appelle les deux dans l'ordre.
+Cette séparation rend possible :
+
+- Tester :func:`build_pareto_section` indépendamment avec un
+  ``engines_summary`` pré-fabriqué.
+- Réutiliser les coûts attachés sans recalculer Pareto.
 """
 
 from __future__ import annotations
@@ -27,13 +40,20 @@ if TYPE_CHECKING:
     from picarones.core.results import BenchmarkResult
 
 
-def build_pareto_section(
+def attach_engine_costs(
     engines_summary: list[dict], benchmark: "BenchmarkResult",
-) -> dict:
-    """Construit le bloc ``pareto`` du dict de rapport.
+) -> None:
+    """Annote chaque entrée de ``engines_summary`` avec son coût.
+
+    **Mute en place** : ajoute deux champs à chaque dict moteur :
+
+    - ``mean_duration_seconds`` (float ou ``None`` si pas de durée).
+    - ``cost`` : dict de la forme ``{cost_per_1k_pages_eur: ...,
+      co2_per_1k_pages_g: ..., ...}`` ou ``None`` si pricing
+      indisponible.
 
-    Annote en place chaque entrée de ``engines_summary`` avec
-    ``mean_duration_seconds`` et ``cost``.
+    Doit être appelée AVANT :func:`build_pareto_section`, qui lit
+    ces deux champs.
     """
     durations_by_engine: dict[str, float] = {}
     for report in benchmark.engine_reports:
@@ -45,11 +65,9 @@ def build_pareto_section(
         if durs:
             durations_by_engine[report.engine_name] = sum(durs) / len(durs)
 
-    pricing_defaults, _ = load_pricing_database()
     costs_by_engine = build_costs_for_benchmark(
         engines_summary, durations_by_engine,
     )
-    # Annoter en place chaque résumé moteur avec son coût et sa durée.
     for entry in engines_summary:
         name = entry["name"]
         entry["mean_duration_seconds"] = (
@@ -58,6 +76,24 @@ def build_pareto_section(
         )
         entry["cost"] = costs_by_engine.get(name)
 
+
+def build_pareto_section(engines_summary: list[dict]) -> dict:
+    """Construit le bloc ``pareto`` du dict de rapport.
+
+    **Fonction pure** : ne mute rien. Lit ``mean_duration_seconds``
+    et ``cost`` qui doivent avoir été attachés en amont par
+    :func:`attach_engine_costs`. Si ces champs sont absents, le
+    moteur est silencieusement omis du front (cohérent avec un
+    moteur qui n'a pas de prix connu).
+
+    Retour
+    ------
+    dict
+        Trois fronts Pareto (``cost``, ``speed``, ``co2``) plus
+        ``pricing_meta`` (table de pricing utilisée).
+    """
+    pricing_defaults, _ = load_pricing_database()
+
     pareto_points = []
     for entry in engines_summary:
         cer = entry.get("cer")
@@ -120,4 +156,4 @@ def build_pareto_section(
     }
 
 
-__all__ = ["build_pareto_section"]
+__all__ = ["attach_engine_costs", "build_pareto_section"]

tests/architecture/test_file_budgets.py

@@ -68,6 +68,10 @@ FILE_BUDGETS: dict[str, int] = {
     "picarones/measurements/numerical_sequences.py": 500, # actuel 422
     "picarones/measurements/normalization.py": 500,       # actuel 420
     "picarones/report/comparison.py": 500,                # actuel 409
+    # --- Module mutualisé créé par le sprint des render helpers
+    # (Sprint « consolidation des renderers » 2026-05-02). Budget
+    # calibré sur la taille post-documentation des conventions.
+    "picarones/report/render_helpers.py": 480,            # actuel 415
 }
 
 

tests/architecture/test_module_coverage.py

@@ -5,14 +5,19 @@ au moins un fichier de production (hors lui-même, hors ``tests/``).
 Sinon le module est *test-only* — sa couverture de test est haute mais
 il n'est branché à rien dans le pipeline réel.
 
-Snapshot v1.0.0 (2026-05-02) : **12 modules** dans ``measurements/``
-n'ont aucun consommateur direct hors tests :
-
-- ``alto_metrics``, ``baseline_comparison``, ``builtin_metrics``,
-  ``cost_projection``, ``equivalence_profile``, ``layout``,
-  ``marginal_cost``, ``ner_backends``, ``rare_tokens``,
-  ``reading_order``, ``taxonomy_cooccurrence``,
-  ``taxonomy_intra_doc``.
+Snapshot v1.0.0 (2026-05-02, recalibré post-audit du 2026-05-02) :
+**13 modules** dans ``measurements/`` n'ont aucun consommateur
+direct hors tests. La baseline initiale (12 modules) reposait sur
+une regex texte qui (a) ne capturait pas la syntaxe
+``from picarones.measurements import X`` utilisée dans
+``__init__.py`` (3 faux positifs : alto_metrics, builtin_metrics,
+reading_order), et (b) capturait à tort les imports DANS DES
+DOCSTRINGS (4 faux négatifs : error_absorption, longitudinal,
+module_policy, reliability).
+
+Le check est désormais basé sur le module ``ast`` standard de
+Python qui ignore correctement le contenu des chaînes/docstrings
+et reconnaît toutes les formes d'import valides.
 
 Trois actions possibles, par module :
 
@@ -32,26 +37,28 @@ Test ratchet :
 
 from __future__ import annotations
 
-import re
+import ast
 from pathlib import Path
 
 REPO_ROOT = Path(__file__).resolve().parents[2]
 PICARONES_DIR = REPO_ROOT / "picarones"
 MEASUREMENTS_DIR = PICARONES_DIR / "measurements"
 
-#: Snapshot v1.0.0. Modules de ``picarones/measurements/`` sans
-#: consommateur en production. À résorber par paliers.
+#: Snapshot v1.0.0 (post-audit AST). Modules de
+#: ``picarones/measurements/`` sans consommateur en production.
+#: À résorber par paliers.
 TEST_ONLY_BASELINE: frozenset[str] = frozenset({
-    "alto_metrics",
     "baseline_comparison",
-    "builtin_metrics",
     "cost_projection",
     "equivalence_profile",
+    "error_absorption",
     "layout",
+    "longitudinal",
     "marginal_cost",
+    "module_policy",
     "ner_backends",
     "rare_tokens",
-    "reading_order",
+    "reliability",
     "taxonomy_cooccurrence",
     "taxonomy_intra_doc",
 })
@@ -65,39 +72,94 @@ def _measurements_modules() -> list[str]:
     )
 
 
+def _imports_target_module(node: ast.AST, module_name: str) -> bool:
+    """True si ce nœud AST importe ``picarones.measurements.<module_name>``.
+
+    Couvre les 5 syntaxes valides Python :
+
+    - ``import picarones.measurements.X``
+    - ``import picarones.measurements.X.sub`` (sous-module)
+    - ``from picarones.measurements.X import Y``
+    - ``from picarones.measurements import X``
+    - ``from picarones.measurements import (X, Y)`` (forme parenthésée)
+    """
+    target_dotted = f"picarones.measurements.{module_name}"
+    if isinstance(node, ast.Import):
+        for alias in node.names:
+            if alias.name == target_dotted or alias.name.startswith(
+                target_dotted + ".",
+            ):
+                return True
+        return False
+    if isinstance(node, ast.ImportFrom):
+        # ``from picarones.measurements.X import …``
+        if node.module == target_dotted:
+            return True
+        # ``from picarones.measurements import X``
+        if node.module == "picarones.measurements":
+            for alias in node.names:
+                if alias.name == module_name:
+                    return True
+    return False
+
+
+def _imports_target_relative(
+    node: ast.AST, module_name: str, source_dir: Path,
+) -> bool:
+    """True si ce nœud AST importe ``module_name`` via un import relatif
+    valide depuis le package ``measurements``.
+
+    Couvre :
+
+    - ``from . import X`` (depuis ``measurements/__init__.py`` ou
+      tout autre module dans le package).
+    - ``from .X import Y``.
+    """
+    if not isinstance(node, ast.ImportFrom):
+        return False
+    if node.level < 1:
+        return False
+    if source_dir != MEASUREMENTS_DIR:
+        return False
+    # ``from .X import …``
+    if node.module == module_name:
+        return True
+    # ``from . import X``
+    if node.module is None:
+        for alias in node.names:
+            if alias.name == module_name:
+                return True
+    return False
+
+
 def _has_production_consumer(module_name: str) -> bool:
     """True si ``module_name`` est importé par un fichier de production.
 
     "Production" = sous ``picarones/``, hors le module lui-même.
-    On accepte les imports absolus (``from picarones.measurements.X``
-    et ``import picarones.measurements.X``) ainsi que les imports
-    relatifs depuis le package ``measurements`` (``from .X``).
+
+    Le check parse l'AST de chaque fichier (au lieu de grep) pour deux
+    raisons :
+
+    1. **Toutes les syntaxes d'import sont reconnues** sans bricolage
+       de regex (``from picarones.measurements import X`` était la
+       grosse cible manquée par la regex initiale).
+    2. **Les chaînes/docstrings ne déclenchent pas de faux positif**
+       (un exemple de code dans une docstring ne compte pas comme
+       import réel).
     """
     own_file = MEASUREMENTS_DIR / f"{module_name}.py"
-    absolute_pattern = re.compile(
-        rf"\bfrom\s+picarones\.measurements\.{re.escape(module_name)}\b"
-        rf"|\bimport\s+picarones\.measurements\.{re.escape(module_name)}\b"
-    )
-    relative_pattern = re.compile(
-        rf"\bfrom\s+\.\s*{re.escape(module_name)}\b"
-        rf"|\bfrom\s+\.measurements\.{re.escape(module_name)}\b"
-    )
     for path in PICARONES_DIR.rglob("*.py"):
         if path == own_file:
             continue
         try:
-            text = path.read_text(encoding="utf-8")
-        except OSError:
+            tree = ast.parse(path.read_text(encoding="utf-8"))
+        except (OSError, SyntaxError):
             continue
-        if absolute_pattern.search(text):
-            return True
-        # Imports relatifs : ne sont valides que depuis l'arbre measurements.
-        try:
-            path.relative_to(MEASUREMENTS_DIR)
-        except ValueError:
-            continue
-        if relative_pattern.search(text):
-            return True
+        for node in ast.walk(tree):
+            if _imports_target_module(node, module_name):
+                return True
+            if _imports_target_relative(node, module_name, path.parent):
+                return True
     return False
 
 

tests/report/test_render_helpers.py

@@ -75,6 +75,28 @@ class TestColorTrafficLight:
         assert len(c) == 7
         assert c == c.lower()
 
+    def test_nan_falls_back_to_red(self) -> None:
+        # max(0, min(1, NaN)) = NaN → mais ensuite f <= 0.5 est False, donc
+        # branche "yellow → green" avec t = (NaN - 0.5) / 0.5 = NaN.
+        # Le résultat est techniquement indéfini ; on vérifie au moins que
+        # la fonction ne crash pas et retourne un hex valide.
+        c = color_traffic_light(float("nan"))
+        assert c.startswith("#")
+        assert len(c) == 7
+
+    def test_inf_clamped_to_max(self) -> None:
+        # +inf > scale_max → clamp à scale_max → vert (high_is_good)
+        assert _hex_to_rgb(color_traffic_light(float("inf"))) == GRADIENT_GREEN_RGB
+        # -inf < 0 → clamp à 0 → rouge
+        assert _hex_to_rgb(color_traffic_light(float("-inf"))) == GRADIENT_RED_RGB
+
+    def test_inverted_scale_returns_yellow(self) -> None:
+        # scale_min > scale_max → span négatif → géré comme zero span.
+        # La fonction ne doit pas crash et retourne une couleur valide.
+        c = color_traffic_light(5.0, scale_min=10, scale_max=5)
+        assert c.startswith("#")
+        assert len(c) == 7
+
 
 # ──────────────────────────────────────────────────────────────────
 # color_single_gradient