test(architecture): 4 invariants structurels contre la dérive silencieuse

Snapshot v1.0.0 (2026-05-02) calibré sur l'état actuel du projet.

- test_file_budgets : budget par fichier (≥ 400 lignes), current + ~15 %
de marge. 27 fichiers surveillés. Garde-fou contre la croissance
silencieuse des god-modules. Le rétrécissement (statistics, generator,
runner) reste un travail séparé.
- test_render_helpers : ratchet à 27 helpers locaux dans picarones/report/
(color_for_*, build_heatmap_svg, etc.). Doit baisser via extraction
vers picarones/report/render_helpers.py.
- test_doc_paths : ratchet à 119 chemins picarones/.../X.py cassés dans
CLAUDE.md, CHANGELOG.md, README.md, docs/**/*.md. Dette documentaire
connue (presque tous les modules described as core/ vivent réellement
dans measurements/).
- test_module_coverage : ratchet sur 12 modules de measurements/ sans
consommateur en production (test-only). À résorber par câblage runner,
déplacement vers extras/, ou suppression.

Chaque test a une fonction "must_be_tightened" qui force à abaisser la
baseline quand on consolide, pour verrouiller le gain.

Re-calibrer à chaque release tag.

tests/architecture/__init__.py

@@ -0,0 +1,16 @@
+"""Invariants structurels du projet.
+
+Ces tests ne vérifient pas un comportement métier mais la **forme**
+du code lui-même : taille des fichiers, unicité des helpers de rendu,
+cohérence des chemins documentés, couverture des modules par un
+consommateur de production.
+
+Ils existent pour casser le cycle « Claude dit que c'est propre ↔
+audit suivant trouve une dérive ». Tant que ces invariants sont verts,
+le projet est *structurellement* sain selon les seuils calibrés au
+dernier release tag. Quand un invariant échoue, c'est un signal de
+réveil : refactor, ou relèvement délibéré du seuil avec
+justification dans le commit.
+
+Re-calibrer à chaque release (``git tag vX.Y.Z``).
+"""

tests/architecture/test_doc_paths.py

@@ -0,0 +1,98 @@
+"""Garde-fou contre la dérive doc-vs-code.
+
+Scanne ``CLAUDE.md``, ``README.md``, ``docs/**/*.md`` à la recherche de
+chemins de la forme ``picarones/.../X.py`` et vérifie qu'ils existent
+dans le repo.
+
+Snapshot v1.0.0 (2026-05-02) : **119 chemins cassés**, presque tous
+dans ``CLAUDE.md`` et ``CHANGELOG.md`` qui décrivent systématiquement
+des modules sous ``picarones/core/...`` alors qu'ils vivent dans
+``picarones/measurements/...``. C'est une dette documentaire connue
+qu'il faut résorber par paliers.
+
+Test ratchet : le nombre de chemins cassés ne peut que diminuer. Pour
+le faire baisser :
+
+1. Soit corriger le chemin dans la doc.
+2. Soit déplacer le module au chemin documenté (rare — la doc se
+   trompe presque toujours).
+3. Soit retirer la référence devenue obsolète.
+
+Puis abaisser :data:`BROKEN_PATHS_BASELINE` du même montant.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+
+#: Snapshot v1.0.0. Doit baisser, jamais monter.
+BROKEN_PATHS_BASELINE = 119
+
+#: Patrons de fichiers de documentation à scanner.
+DOC_GLOBS: tuple[str, ...] = (
+    "CLAUDE.md",
+    "README.md",
+    "CHANGELOG.md",
+    "SPECS.md",
+    "docs/**/*.md",
+)
+
+#: Pattern minimal d'un chemin Python dans le repo.
+PATH_PATTERN: re.Pattern[str] = re.compile(
+    r"picarones/[a-z_][a-z_0-9]*(?:/[a-z_][a-z_0-9]*)*\.py"
+)
+
+
+def _doc_files() -> list[Path]:
+    files: list[Path] = []
+    for glob in DOC_GLOBS:
+        files.extend(REPO_ROOT.glob(glob))
+    return sorted({f for f in files if f.is_file()})
+
+
+def _broken_paths() -> list[tuple[str, str]]:
+    """Liste des (doc_relatif, chemin_cassé), dédoublonnée et triée."""
+    broken: set[tuple[str, str]] = set()
+    for doc in _doc_files():
+        try:
+            text = doc.read_text(encoding="utf-8")
+        except OSError:
+            continue
+        rel_doc = doc.relative_to(REPO_ROOT).as_posix()
+        for match in PATH_PATTERN.findall(text):
+            if not (REPO_ROOT / match).exists():
+                broken.add((rel_doc, match))
+    return sorted(broken)
+
+
+def test_broken_doc_paths_below_baseline() -> None:
+    """Le nombre de chemins cassés ne peut que diminuer."""
+    broken = _broken_paths()
+    if len(broken) > BROKEN_PATHS_BASELINE:
+        sample = "\n".join(f"  {doc} → {path}" for doc, path in broken[:30])
+        more = f"\n  ... ({len(broken) - 30} de plus)" if len(broken) > 30 else ""
+        raise AssertionError(
+            f"\n{len(broken)} chemins de doc cassés (baseline "
+            f"{BROKEN_PATHS_BASELINE}).\n"
+            f"Régression : la doc référence un fichier qui n'existe pas.\n\n"
+            f"Échantillon :\n{sample}{more}\n\n"
+            "Soit corrige le chemin, soit le code, soit retire la référence."
+        )
+
+
+def test_baseline_must_be_tightened_when_progress_made() -> None:
+    """Si on est sous le baseline, mettre à jour :data:`BROKEN_PATHS_BASELINE`.
+
+    Verrouille chaque correction de doc pour empêcher une régression
+    future de glisser sous le seuil obsolète.
+    """
+    broken = _broken_paths()
+    assert len(broken) >= BROKEN_PATHS_BASELINE, (
+        f"\nExcellent : {len(broken)} chemins cassés vs baseline "
+        f"{BROKEN_PATHS_BASELINE}.\n\n"
+        f"Mets à jour BROKEN_PATHS_BASELINE = {len(broken)} dans "
+        "tests/architecture/test_doc_paths.py pour verrouiller le gain."
+    )

tests/architecture/test_file_budgets.py

@@ -0,0 +1,125 @@
+"""Garde-fou contre la croissance silencieuse des fichiers.
+
+Chaque fichier listé dans :data:`FILE_BUDGETS` a un budget en lignes.
+Si un fichier dépasse son budget, le test échoue et la PR est forcée
+à choisir entre :
+
+1. **Refactor** pour rentrer dans le budget (extraire un sous-module,
+   factoriser, supprimer du code mort).
+2. **Relever le budget délibérément** : modifier la valeur dans ce
+   fichier en l'expliquant dans le message de commit. La hausse devient
+   un acte conscient, plus une dérive silencieuse.
+
+Calibration : snapshot v1.0.0 (2026-05-02), ``current + ~15 %`` de marge
+pour l'évolution naturelle. Les god-modules historiques (statistics,
+generator, runner) gardent un budget proche de leur taille actuelle ; le
+choix de les dégonfler est une décision dédiée à un sprint de refactor,
+pas un sous-produit de l'invariant.
+
+Re-calibrer à chaque release tag.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+
+
+# Format : chemin relatif → max_lines.
+# Seuls les fichiers ≥ 400 lignes sont surveillés (les petits fichiers
+# n'ont pas besoin de budget — leur croissance est gérée par les tests
+# de couverture, pas par un seuil dur).
+FILE_BUDGETS: dict[str, int] = {
+    # --- God-modules : budget actuel + 15 % de marge.
+    # Le rétrécissement sera l'objet d'un sprint de refactor dédié.
+    "picarones/measurements/statistics.py": 1300,         # actuel 1128
+    "picarones/report/generator.py": 1250,                # actuel 1063
+    "picarones/measurements/runner.py": 1200,             # actuel 1019
+    # --- Fichiers métier larges.
+    "picarones/measurements/robustness.py": 850,          # actuel 731
+    "picarones/report/pipeline_render.py": 825,           # actuel 717
+    "picarones/core/results.py": 750,                     # actuel 636
+    "picarones/report/philological_render.py": 725,       # actuel 615
+    "picarones/measurements/history.py": 725,             # actuel 615
+    "picarones/measurements/modern_archives.py": 700,     # actuel 599
+    "picarones/measurements/builtin_hooks.py": 700,       # actuel 590
+    "picarones/core/pipeline.py": 675,                    # actuel 571
+    "picarones/extras/importers/iiif.py": 675,            # actuel 567
+    "picarones/extras/importers/gallica.py": 675,         # actuel 563
+    "picarones/measurements/levers.py": 675,              # actuel 561
+    "picarones/extras/importers/escriptorium.py": 650,    # actuel 553
+    "picarones/web/security.py": 625,                     # actuel 532
+    "picarones/core/corpus.py": 600,                      # actuel 511
+    "picarones/fixtures.py": 600,                         # actuel 510
+    "picarones/measurements/inter_engine.py": 575,        # actuel 484
+    "picarones/measurements/roman_numerals.py": 575,      # actuel 478
+    "picarones/extras/importers/htr_united.py": 575,      # actuel 473
+    "picarones/cli/_workflows.py": 550,                   # actuel 469
+    "picarones/extras/importers/huggingface.py": 550,     # actuel 464
+    "picarones/core/metric_hooks.py": 500,                # actuel 423
+    "picarones/measurements/numerical_sequences.py": 500, # actuel 422
+    "picarones/measurements/normalization.py": 500,       # actuel 420
+    "picarones/report/comparison.py": 500,                # actuel 409
+}
+
+
+def _line_count(path: Path) -> int:
+    """Compte les lignes physiques (y compris vides)."""
+    return len(path.read_text(encoding="utf-8").splitlines())
+
+
+@pytest.mark.parametrize(
+    ("rel_path", "budget"),
+    sorted(FILE_BUDGETS.items()),
+)
+def test_file_size_within_budget(rel_path: str, budget: int) -> None:
+    """Chaque fichier surveillé doit rester ≤ budget."""
+    path = REPO_ROOT / rel_path
+    assert path.exists(), (
+        f"Fichier disparu : {rel_path}. "
+        "Retire l'entrée de FILE_BUDGETS dans "
+        "tests/architecture/test_file_budgets.py."
+    )
+    actual = _line_count(path)
+    assert actual <= budget, (
+        f"\n{rel_path} a {actual} lignes (budget {budget}).\n\n"
+        "Soit refactor pour rentrer dans le budget, soit relève le budget "
+        "consciemment dans tests/architecture/test_file_budgets.py "
+        "avec une justification dans le message de commit."
+    )
+
+
+def test_no_orphaned_budget_entries() -> None:
+    """Toute entrée de FILE_BUDGETS doit pointer vers un fichier existant."""
+    missing = [p for p in FILE_BUDGETS if not (REPO_ROOT / p).exists()]
+    assert not missing, (
+        f"Entrées orphelines dans FILE_BUDGETS : {missing}. "
+        "Le fichier a été déplacé/supprimé — retire l'entrée."
+    )
+
+
+def test_budget_table_covers_all_large_files() -> None:
+    """Tout fichier ≥ 400 lignes doit avoir une entrée dans FILE_BUDGETS.
+
+    Empêche un fichier nouveau ou subitement gros d'échapper à la
+    surveillance. Si un fichier dépasse 400 lignes, ajoute-le à
+    FILE_BUDGETS avec son budget (current + 15 %).
+    """
+    threshold = 400
+    untracked: list[tuple[str, int]] = []
+    for path in (REPO_ROOT / "picarones").rglob("*.py"):
+        rel = path.relative_to(REPO_ROOT).as_posix()
+        if rel in FILE_BUDGETS:
+            continue
+        count = _line_count(path)
+        if count >= threshold:
+            untracked.append((rel, count))
+    assert not untracked, (
+        f"\nFichiers ≥ {threshold} lignes non surveillés :\n"
+        + "\n".join(f"  {p} ({n} lignes)" for p, n in sorted(untracked))
+        + "\n\nAjoute-les à FILE_BUDGETS dans "
+        "tests/architecture/test_file_budgets.py avec budget = current + ~15 %."
+    )

tests/architecture/test_module_coverage.py

@@ -0,0 +1,141 @@
+"""Garde-fou contre les modules sans consommateur en production.
+
+Chaque module dans ``picarones/measurements/`` doit être importé par
+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``.
+
+Trois actions possibles, par module :
+
+1. **Câbler** dans le runner ou un renderer (le module devient un
+   produit, pas une expérience).
+2. **Déplacer** vers ``picarones/extras/`` si c'est expérimental
+   et non livré dans le pipeline standard.
+3. **Retirer** si c'est mort (le travail reste dans l'historique git).
+
+Test ratchet :
+
+- Tout module ``measurements/X.py`` qui devient test-only sans entrer
+  dans la baseline → échec (régression).
+- Tout module de la baseline qui gagne un consommateur → échec
+  jusqu'à ce que la baseline soit mise à jour pour verrouiller le gain.
+"""
+
+from __future__ import annotations
+
+import re
+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.
+TEST_ONLY_BASELINE: frozenset[str] = frozenset({
+    "alto_metrics",
+    "baseline_comparison",
+    "builtin_metrics",
+    "cost_projection",
+    "equivalence_profile",
+    "layout",
+    "marginal_cost",
+    "ner_backends",
+    "rare_tokens",
+    "reading_order",
+    "taxonomy_cooccurrence",
+    "taxonomy_intra_doc",
+})
+
+
+def _measurements_modules() -> list[str]:
+    return sorted(
+        p.stem
+        for p in MEASUREMENTS_DIR.glob("*.py")
+        if p.stem != "__init__"
+    )
+
+
+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``).
+    """
+    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:
+            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
+    return False
+
+
+def _test_only_modules() -> frozenset[str]:
+    return frozenset(
+        m for m in _measurements_modules()
+        if not _has_production_consumer(m)
+    )
+
+
+def test_no_new_test_only_modules() -> None:
+    """Aucun module ne doit devenir test-only sans entrer dans la baseline."""
+    current = _test_only_modules()
+    new = current - TEST_ONLY_BASELINE
+    assert not new, (
+        f"\n{len(new)} module(s) de measurements/ sans consommateur en "
+        f"production : {sorted(new)}.\n\n"
+        "Choisis l'une des trois options :\n"
+        "  1. Câble le module dans le runner ou un renderer.\n"
+        "  2. Déplace-le sous picarones/extras/ s'il est expérimental.\n"
+        "  3. Retire-le si c'est mort.\n\n"
+        "En dernier recours, ajoute son nom à TEST_ONLY_BASELINE dans "
+        "tests/architecture/test_module_coverage.py — c'est admettre "
+        "consciemment qu'il vit hors du pipeline standard."
+    )
+
+
+def test_baseline_modules_still_orphaned() -> None:
+    """Si un module de la baseline a gagné un consommateur, lock le gain.
+
+    Force à mettre à jour la baseline pour verrouiller chaque câblage,
+    sinon une régression future re-deviendrait test-only sans alerte.
+    """
+    current = _test_only_modules()
+    fixed = TEST_ONLY_BASELINE - current
+    assert not fixed, (
+        f"\nExcellent : {len(fixed)} module(s) ont gagné un consommateur en "
+        f"production : {sorted(fixed)}.\n\n"
+        "Retire ces noms de TEST_ONLY_BASELINE dans "
+        "tests/architecture/test_module_coverage.py pour verrouiller le gain."
+    )

tests/architecture/test_render_helpers.py

@@ -0,0 +1,107 @@
+"""Garde-fou contre la prolifération des helpers de rendu.
+
+Les renderers HTML dans ``picarones/report/`` ont accumulé des helpers
+locaux dupliqués (couleur, heatmap SVG, etc.) qui devraient vivre dans
+un unique ``picarones/report/render_helpers.py``.
+
+Snapshot v1.0.0 (2026-05-02) :
+
+- 25 fonctions ``_color_for_*`` distinctes (dont plusieurs portent le
+  même nom dans des fichiers différents : ``_color_for_score`` ×5,
+  ``_color_for_delta`` ×2, ``_color_for_cer`` ×2).
+- 1 fonction ``_color`` simple (``inter_engine_render``).
+- 2 fonctions ``_build_heatmap_svg`` (``taxonomy_cooccurrence``,
+  ``taxonomy_intra_doc``).
+
+Soit **27 helpers locaux** dupliqués.
+
+Test ratchet : ce nombre ne peut que descendre. Pour le faire baisser,
+extraire un helper dans ``picarones/report/render_helpers.py`` et
+l'importer depuis les renderers qui en avaient besoin, puis abaisser
+:data:`HELPER_BASELINE` du même montant.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+REPORT_DIR = REPO_ROOT / "picarones" / "report"
+
+#: Snapshot v1.0.0. Doit baisser, jamais monter.
+HELPER_BASELINE = 27
+
+#: Le module mutualisé est exempté (c'est *là* qu'on veut les voir).
+HELPERS_MODULE_NAME = "render_helpers.py"
+
+#: Fichiers à ignorer (pas des renderers).
+IGNORED_FILES: frozenset[str] = frozenset({"__init__.py", HELPERS_MODULE_NAME})
+
+#: Patterns capturant les helpers à mutualiser.
+#:
+#: On vise spécifiquement la duplication observée : coloration et
+#: builders SVG génériques. Les helpers vraiment locaux (extraction
+#: depuis une structure de données spécifique au domaine, formatage
+#: dépendant de la métrique) ne sont *pas* visés.
+HELPER_PATTERNS: tuple[re.Pattern[str], ...] = (
+    re.compile(r"^def\s+_color_for\w*\s*\("),
+    re.compile(r"^def\s+_color\s*\("),
+    re.compile(r"^def\s+_build_heatmap\w*\s*\("),
+)
+
+
+def _scan_helpers() -> list[tuple[str, int, str]]:
+    """Retourne la liste des (chemin_relatif, ligne, signature)."""
+    found: list[tuple[str, int, str]] = []
+    for path in sorted(REPORT_DIR.rglob("*.py")):
+        if path.name in IGNORED_FILES:
+            continue
+        try:
+            text = path.read_text(encoding="utf-8")
+        except OSError:
+            continue
+        for line_num, line in enumerate(text.splitlines(), 1):
+            for pattern in HELPER_PATTERNS:
+                if pattern.match(line):
+                    rel = path.relative_to(REPO_ROOT).as_posix()
+                    found.append((rel, line_num, line.strip()))
+                    break
+    return found
+
+
+def test_render_helpers_below_baseline() -> None:
+    """Le nombre de helpers locaux ne peut que descendre.
+
+    Quand on consolide un helper vers ``render_helpers.py``, abaisser
+    aussi :data:`HELPER_BASELINE` dans le même commit pour verrouiller
+    le gain.
+    """
+    helpers = _scan_helpers()
+    count = len(helpers)
+    locations = "\n".join(
+        f"  {rel}:{line} — {sig}" for rel, line, sig in helpers
+    )
+    assert count <= HELPER_BASELINE, (
+        f"\n{count} helpers locaux trouvés (baseline {HELPER_BASELINE}).\n"
+        f"Régression : un nouveau helper a été ajouté.\n\n"
+        f"Localisations :\n{locations}\n\n"
+        "Soit déplace ce helper dans picarones/report/render_helpers.py "
+        "et importe-le, soit relève HELPER_BASELINE consciemment dans "
+        "tests/architecture/test_render_helpers.py."
+    )
+
+
+def test_baseline_must_be_tightened_when_progress_made() -> None:
+    """Si le compte est sous le baseline, abaisse :data:`HELPER_BASELINE`.
+
+    Force à verrouiller chaque consolidation : sans cette étape, le
+    progrès n'est pas figé et une régression future passerait inaperçue
+    sous le seuil obsolète.
+    """
+    count = len(_scan_helpers())
+    assert count >= HELPER_BASELINE, (
+        f"\nExcellent : {count} helpers vs baseline {HELPER_BASELINE}.\n\n"
+        f"Mets à jour HELPER_BASELINE = {count} dans "
+        "tests/architecture/test_render_helpers.py pour verrouiller le gain."
+    )