[design] Ergonomie de compare_datasets_from_yaml : 17 paramètres, franglais $reponse, triple all_passed, WARN/STOP jumeaux — proposition d'API 0.5

[VincentGuyader]

Contexte

Constats UX convergents sur la fonction centrale (aucun n'est un bug isolé — c'est le design d'ensemble) :

1. 17 paramètres à plat, dont 5 de pur passe-plat vers pointblank::interrogate() (extract_failed, get_first_n, sample_n, sample_frac, sample_limit) et 1 actif sur un seul chemin (duckdb_memory_limit).
2. Franglais : argument data_reference (EN) mais champ retour $reponse (FR, sans accent) au milieu de champs anglais ; messages 100 % anglais mais rapport par défaut en français.
3. Redondances du retour : all_passed en 3 exemplaires ($all_passed, $summary$all_passed, pointblank::all_passed($reponse)) ; $agent non interrogé (et factice sur le fast-path all-pass) sans usage utilisateur identifié.
4. warn_at/stop_at identiques (1e-14, écrits en littéral décimal de 14 zéros) : WARN et STOP se déclenchent toujours ensemble — le niveau WARN n'apporte rien en l'état ; et la reconstitution warn/stop du rapport suppose des seuils fractionnaires alors que pointblank interprète ≥ 1 comme un compte absolu.
5. Messages laconiques : message("key is missing") à chaque comparaison positionnelle légitime ; contraste avec les excellents warnings doublons/type_mismatch (contexte + exemples + action).
6. Nom : compare_datasets_from_yaml alors que le YAML est optionnel depuis 0.1.5 — un alias compare_datasets() refléterait l'usage réel.
7. ref_suffix expose un détail d'implémentation ; write_rules_template() a 19 paramètres au nommage incohérent (na_equal_default vs numeric_abs) et écrit par défaut rules.yaml dans le répertoire courant.

Proposition (à discuter)

compare_datasets(reference, candidate, key = NULL, rules = NULL,
                 extract = extract_opts(first_n = NULL, sample_n = NULL, ...),
                 engine  = engine_opts(duckdb_memory_limit = "8GB", ...),
                 lang = getOption("datadiff.lang", "en"), ...)
# retour de classe datadiff_result : $passed, $coverage, $summary, $report (lazy), print() dédié
# compare_datasets_from_yaml() conservé en alias rétrocompatible

Critères de succès

• RFC/discussion tranchée sur : langue de l'API (proposition : anglais partout, reponse → report avec alias déprécié), objets d'options, sort de $agent, alias compare_datasets().
• Cycle de dépréciation propre (warnings conditionnels, une version de grâce, entrées NEWS).
• warn_at/stop_at : sémantique documentée, défauts distincts ou paramètre unique fail_at.
• Messages uniformisés sur le style des bons warnings existants (contexte + conséquence + action).
• Vignette et README réécrits sur la nouvelle surface, anciens noms documentés en annexe migration.

[VincentGuyader]

Le RFC est poste : dev/RFC-api-0.5.md (PR #54, hors tarball).

Resume des propositions a trancher pour la 0.5 :

1. compare_datasets() comme nom principal, compare_datasets_from_yaml() alias deprecie en 3 versions (soft warning -> warning -> retrait)
2. extract_opts() / engine_opts() : les 15+ parametres regroupes en objets d'options valides des la construction
3. Retour de classe datadiff_result : passed" + "report", depreciation des doublons all_passed/reponse` (le $reponse francais au milieu d'une API anglaise)
4. fail_at unique a la place du couple warn_at/stop_at (le verdict binaire n'exploite pas la nuance)
5. lang = "en" par defaut (via getOption("datadiff.lang", "en")), annonce en Breaking changes

Les quick wins non cassants de l'issue sont deja livres dans audit-0.4.10 : erreurs de cle explicites (#16), precedence YAML/arguments documentee et testee (#20), cols_reference deprecie (#25), contradictions NEWS resolues (#26), equal_mode effectif (#27), duckdb_memory_limit valide (#30).

Rien de tout cela n'est implemente : l'issue reste ouverte pour la discussion. Mon avis : (1), (3) et (5) valent le cout de la casse ; (2) est du confort ; (4) merite un contre-avis utilisateur.