feat(sql): standard DuckDB macros per il layer CLEAN

[Gabrymi93]

Sintesi

7 macro DuckDB caricate automaticamente in ogni esecuzione clean.sql, per eliminare il boilerplate SQL che oggi è riscritto da zero in ogni dataset di dataset-incubator (TRY_CAST, REPLACE numeri italiani, CASE decode flag, TRIM).

Contesto collegato

Segue la discussione architetturale: toolkit può snellire DI? I pattern comuni nei clean.sql sono stati analizzati e le macro coprono l'80% del boilerplate.

Cosa cambia

• Bug fix
• Nuova funzionalità del motore
• Nuovo plugin sorgente
• Modifica contratto pubblico (dataset.yml, path output, schema parquet)
• Refactor / performance
• Documentazione
• Dipendenze o CI

Impatto su contratti pubblici

Nessuno. Le macro sono additive — un clean.sql che non le usa funziona identico.

Cosa contiene

toolkit/sql/macros.sql — 7 macro DuckDB

Macro	Trasformazione	Frequenza in DI
normalize_italian_number(val)	1.234,56 → 1234.56	40%
normalize_italian_integer(val)	1.234 → 1234	30%
decode_flag(val, 'X')	'X' → TRUE	30%
normalize_string(val)	TRIM + '' → NULL	100%
cast_int(val)	TRY_CAST(val AS INTEGER)	100%
cast_double(val)	TRY_CAST(val AS DOUBLE)	100%
remove_dot_thousands(val)	1.234 → 1234.0	20%

toolkit/clean/sql_execute.py — caricamento automatico

_load_standard_macros(con, logger) chiamata all'inizio di ogni _run_sql(), prima della vista raw_input. I file macro sono dentro il pacchetto toolkit (toolkit/sql/macros.sql), raggiungibili da qualsiasi dataset.

toolkit/scaffold/clean.py — documentazione nello scaffold

Il generated SQL ora include un commento con l'elenco delle macro disponibili.

Test: tests/test_macros_sql.py — 35 test pure_unit

• 7 test normalize_italian_number (base, migliaia, decimali, null, non-numerico, vuoto)
• 4 test normalize_italian_integer
• 6 test decode_flag (match, mismatch, case-sensitive, trim, null)
• 4 test normalize_string (trim, vuoto, whitespace, null)
• 4 test cast_int (stringa, intero, non-numerico, null)
• 4 test cast_double (stringa, decimale, non-numerico, null)
• 4 test remove_dot_thousands
• 1 test integrazione (simula un clean.sql reale con 3 righe e tutte le macro)

Esempio di impatto su un clean.sql reale

Prima (ade-cinque-per-mille):

TRY_CAST(REPLACE(REPLACE("Importo delle scelte espresse"::VARCHAR, '.', ''), ',', '.') AS DOUBLE) AS importo_scelte_espresse,
CASE WHEN TRIM("ETS") = 'X' THEN TRUE ELSE FALSE END AS flag_ets_onlus,
TRIM("Codice fiscale") AS codice_fiscale,

Dopo:

normalize_italian_number("Importo delle scelte espresse") AS importo_scelte_espresse,
decode_flag("ETS", 'X') AS flag_ets_onlus,
normalize_string("Codice fiscale") AS codice_fiscale,

Verifica

pytest tests/test_macros_sql.py -v
pytest -m pure_unit -q

• pytest tests/test_macros_sql.py passa (35 test)
• pytest -m pure_unit passa (457 test)
• ruff check . passa
• Tutti i test nuovi sono marker pure_unit
• 2 test esistenti aggiornati per escludere i commenti macro dalle assertions (test_scaffold_clean, test_scout_infer)

Checklist PR

• Perimetro stretto: un file macro SQL + caricamento + test
• Nessuna modifica a contratti pubblici esistenti
• Test presenti con marker appropriato

Note per chi revisiona

• Le macro sono CREATE OR REPLACE — sicure da eseguire più volte
• La funzione _load_standard_macros() ignora silenziosamente se macros.sql non esiste (sicura in sviluppo)
• remove_dot_thousands è intenzionalmente solo per interi — numeri con virgola decimale vanno con normalize_italian_number