refactor: elimina 4 duplicazioni CLI, sposta sql_dry_run in core

[Gabrymi93]

Sintesi

Elimina 4 punti di duplicazione tra CLI e moduli interni del toolkit.
Sposta sql_dry_run.py da cli/ a core/sql_validation.py (non è logica CLI).
Rimuove _batch_helpers.py (orfano dopo refactor _run_batch).

Cosa cambia

• Refactor / performance
• Documentazione (ADR-003)

Impatto su contratti pubblici

• Modulo spostato (sql_dry_run) con backward compat stub + DeprecationWarning

Se segnato, hai aggiornato downstream? [ ] dataset-incubator — [ ] docs/

Cosa è stato fatto

Cosa	Dove	Delta
dump_cfg_section → re-export di ensure_dict	common.py	−20
_quoted_identifier → q_ident	sql_dry_run.py	−3
sql_dry_run.py → core/sql_validation.py	spostamento	+234 −239 (stub)
_batch_helpers.py rimosso (orfano)	—	−79
_run_pipeline/_execute_pipeline separati	cmd_run.py 1267→975	−292
ADR-003 marcato superseded	docs	—
Totale	12 file	−167 nette

Verifica

pytest -x --tb=short -q    # 1234 passano
ruff check .               # OK
python -c "from toolkit.cli.sql_dry_run import validate_sql_dry_run"  # DeprecationWarning

• pytest -m core passa
• ruff check . passa
• mypy toolkit/ passa (2 errori preesistenti in read_excel.py e profile/raw.py, non toccati)
• Modulo sql_dry_run rimosso: verificato con rg su org, lasciato stub backward compat

Checklist PR

• Perimetro stretto: CLI duplicazioni + misplaced module
• Se rimuovo un modulo/funzione pubblica: rg verificato, shim backward compat con DeprecationWarning

Note per chi revisiona

• sql_dry_run.py è ora uno stub che re-exporta da core/sql_validation.py e stampa DeprecationWarning
• common.py:dump_cfg_section è ora un alias di core.config.ensure_dict (stessa logica, firma identica)
• _batch_helpers.py non era importato da nessun modulo di produzione (solo da test, rimosso)
• cmd_run.py da 1267 a 975 righe: _run_pipeline() (esecuzione pura) separata da _execute_pipeline() (presentazione CLI)

[Gabrymi93]

Fix review applicati (commit 00bce14)

Critical — exit code batch

• _run_batch ora esce con code=1 se failures o qualsiasi riga non è SUCCESS/DRY_RUN
• _run_pipeline ritorna status="failed" senza eccezione (config check fallito, run per-anno fallito) → il report marcava la riga FAILED ma usciva con 0. Riprodotto e fixato.
• Test di regressione: test_run_batch_exit_nonzero_when_config_invalid

Medium — DRY_RUN nel report

• Ri-segnalato: in dry-run un esito ok è DRY_RUN, non SUCCESS
• summary.passed conta SUCCESS + DRY_RUN (come il vecchio batch)
• Test ripristinati: test_batch_step_probe_dry_run_reports_dry_run verifica di nuovo status == "DRY_RUN"

Medium — assert sui messaggi dry-run

• test_run_dry_run_fails_on_clean_sql_syntax_error e ..._mart_sql_binding_error verificano di nuovo la ragione del fallimento ("CLEAN SQL"/"MART SQL" + "dry-run failed" + "Parser Error"/"Binder Error")
• Nota: il logger rich spezza le righe, quindi gli assert usano l'output normalizzato

Low — ensure_dict vs dump_cfg_section

• Verificato: entrambe le funzioni droppano i campi None nelle dataclass ({k: v ... if v is not None}). Il claim "il vecchio dump_cfg_section li includeva" non corrisponde al codice. Nessuna regressione reale.
• Documentato il filtro None su ensure_dict per i consumer

Low — config test batch

• Aggiunte read.columns esplicite (comune/anno/valore) al config di test per far passare la SQL validation in dry-run

Test: 1235 passano, 0 falliti.