[Gabrymi93]

Sintesi

Due difetti piccoli ma silenziosi nel catalog engine, emersi osservando il portale MEF analisi_stat (fonte del repo dichiarazioni-italia) e ricondotti a un caso minimo riproducibile. Entrambi falsano il segnale senza errori: il catalogo di una fonte risulta "validato" o "nuovo contenuto" quando non lo è.

Contesto collegato

Closes #433

Cosa cambia

• Modifica script (radar, inventory, source-check, MCP)
• Nuova fonte o modifica registro (sources_registry.yaml)
• Source-check o inventory-triage
• Modifica funnel o criteri di osservazione
• Workflow CI (radar.yml, observatory.yml)
• Skills o MCP tools
• Documentazione (docs/runbook.md)

1. validate troncava l'URL a ?

scripts/collectors/_validate_base.py faceva url = url_raw.split("?")[0] prima del probe. Per le fonti che servono il dato via query-string — index.php?tree=2025CIVATOT0201&export=3 — validava la pagina HTML del portale invece del file: is_csv falso, probe sul target sbagliato, reachable/readiness sbagliati.

Ora l'URL intero va al probe; il path senza query serve solo a indovinare il formato.

2. pattern_probes: 200 vuoto contava come disponibile

available = 200 <= status < 300. MEF risponde 200 con 0 byte per l'anno non ancora pubblicato, quindi new_content_available sarebbe scattato a ogni build, per sempre: il segnale "nuovo contenuto" diventava rumore.

Nuovo campo opzionale min_bytes per entry (default 0, retro-compatibile), con below_min_bytes: true nel risultato per il debug e validazione in [tool.observatory] (intero ≥ 0, errore leggibile).

Documentazione

pattern_probes non era documentato da nessuna parte: aggiunta una sottosezione in docs/runbook.md (catalog per-repo, sintassi, min_bytes) con l'esempio MEF.

Checklist

Se modifichi script o MCP

• pytest tests/ passa
• ruff check . passa
• mypy scripts/ so_mcp/ passa
• Comando manuale verificato (sotto)

Verifica

Test aggiunti (8):

• validate con URL a query-string: l'URL integro arriva al probe e resta in result["url"]
• URL senza estensione nel path (index.php?...&export=3): è il campo format a decidere il probe
• probe_pattern: 2xx con 0 byte + min_bytes=200 → available=False, below_min_bytes=True
• probe_pattern: 2xx sopra soglia → available=True, nessun below_min_bytes
• run_pattern_probes: min_bytes dell'entry arriva al probe (e valore non valido → 0)
• config: pattern_probes.min_bytes rifiutato se non intero ≥ 0 (2 test: negativo, stringa)

Aggiornati i fake che mockavano l'URL troncato (MEF_URL_NO_QUERY), che documentavano il comportamento precedente.

Verifica manuale sulla fonte reale:

caso	esito
validate su index.php?tree=2025CIVATOT0201&export=3	reachable=True, result["url"] con query integra, probe sul file reale (200). Lo sniff dello schema resta debole (num_columns=1, delim ,) per il preambolo di 9 righe: limite dichiarato, rimandato a #434
probe_pattern su tree=2025DIRTOT020001 (0 byte)	senza soglia → available=True ❌ · con min_bytes=200 → available=False ✅
probe_pattern su tree=2024DIRTOT020001 (dato presente)	available=True, 5381 byte ✅

Note

• Limite noto, fuori scope: per questi CSV lo sniff dello schema resta debole per via del preambolo di 9 righe (il csv.Sniffer sceglie , invece di ; → 1 colonna). Serve un hint esplicito (skip_lines/delimiter) nell'extraction mode di html collector: extraction mode per portali ad albero con export a query-string (MEF analisi_stat) #434 — dettagli e misure nel commento su html collector: extraction mode per portali ad albero con export a query-string (MEF analisi_stat) #434.
• Il default min_bytes=0 mantiene il comportamento attuale per le fonti già in produzione: nessun cambio per i cataloghi esistenti.
• content_length è ora valorizzato anche sotto soglia (2xx) invece di None: cambio semantico minore, lo schema lo consente.
• La query-string ora finisce nei parquet tracciati: nota esplicita in docs/runbook.md, redazione dei parametri sensibili tracciata in validate: redigere i parametri sensibili delle query-string negli artifact tracciati #436.