feat: aggiungi supporto esplicito a output cross_year

[Gabrymi93]

Obiettivo

Aggiungere nel toolkit un supporto esplicito e opzionale per output multi-anno (cross_year), mantenendo raw, clean e mart year-scoped.

Cosa cambia

Questa PR introduce:

• nuova sezione config cross_year
• nuovo comando CLI:
  • toolkit run cross_year --config dataset.yml
• nuovo layer di output:
  • root/data/cross/<dataset>/
• supporto a sorgenti annuali da:
  • clean
  • mart (con source_table esplicito)

Shape supportata

cross_year:
  tables:
    - name: irpef_capacita_fiscale_multi_anno
      sql: sql/mart_multi_anno.sql
      source_layer: clean

Oppure, se la sorgente è mart:

cross_year:
  tables:
    - name: foo
      sql: sql/cross/foo.sql
      source_layer: mart
      source_table: bar_table

Scelte di design della v1

• cross_year è esplicito, non automatico
• non entra in run all
• non introduce validation dedicata in questa PR
• gli output sono separati dagli output annuali
• il runner espone alias compatibili:
  • clean_input
  • clean
  • clean_all_years
  • analogamente per mart

Perché

Nel toolkit attuale, raw, clean e mart girano per singolo anno.

Questo è corretto per la pipeline base, ma non copre bene casi reali in cui il primo output analitico utile è cross-year. Il caso che ha guidato la feature è:

• IRPEF comunale 2019-2023

File principali

• toolkit/core/config_models.py
• toolkit/core/config.py
• toolkit/cli/cmd_run.py
• toolkit/core/paths.py
• toolkit/core/metadata.py
• toolkit/cross/run.py
• docs/config-schema.md
• tests/test_cross_year.py

Commit inclusi

• 4847862 feat: aggiungi supporto cross_year esplicito
• 6cc94be docs: documenta il layer cross_year
• e0bab62 fix: aggiungi alias *_all_years nel runner cross_year

Test

Test automatici passati:

• python -m pytest tests/test_cross_year.py
• python -m pytest tests/test_config.py -k "resolves_relative_paths_from_dataset_dir"

Test reale

Validato sul caso reale:

• dataciviclab/preanalysis/irpef-comunale-2019-2023

Comandi eseguiti:

py -m toolkit.cli.app run all --config preanalysis/irpef-comunale-2019-2023/dataset.yml
py -m toolkit.cli.app run cross_year --config preanalysis/irpef-comunale-2019-2023/dataset.yml

Output prodotto:

• dataciviclab/_out/data/cross/irpef_comunale_2019_2023/irpef_capacita_fiscale_multi_anno.parquet

Verifiche rapide:

• 39511 righe comune
• 110 righe regione
• copertura anni 2019-2023

Note

La feature resta volutamente stretta:

• nessun automatismo implicito per tutti i dataset con years
• nessuna dependency chain tra tabelle cross_year
• nessuna validation dedicata del layer in questa PR

L’obiettivo qui è introdurre un contract nativo minimo ma già usabile su un caso reale.