fix: test motore (003/002/001 + determinismo + fail-closed), CI, note deterministiche, allineamento required_fields REGOLA-003 e README

Author: superpios

.github/workflows/ci.yml

@@ -0,0 +1,19 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install dependencies
+        run: pip install -r requirements.txt
+      - name: Run tests
+        run: python -m pytest tests/ -q

README.md

@@ -8,7 +8,7 @@ Nessuna pista dimostra, suggerisce o implica illecito, spreco, frode o responsab
 **Progetto collegato** al repository madre [DoveVannoINostriSoldi](https://github.com/Italian-Builders-Org/DoveVannoINostriSoldi) (Fase 5 della ROADMAP).
 
 ## Cosa fa
-- Legge le tabelle di relazione (formato definito in `schemas/` dell'Explorer)
+- Legge le tabelle di relazione (CSV) esportate da `investigative-explorer-dvns` (in `data/relations/` dell'Explorer); lo schema di ogni pista in uscita è in `docs/FORMATO_PISTA.md`
 - Applica regole dichiarative estremamente caute (YAML)
 - Produce piste in JSON + Markdown con provenienza completa
 - È completamente deterministico (stesso input → stesso output)
@@ -32,5 +32,9 @@ python scripts/apply_rules.py --input data/input --output data/leads --rules rul
 | docs/FORMATO_PISTA.md | Schema obbligatorio di ogni pista |
 | docs/LIMITI.md | Limiti metodologici e interpretativi |
 
+## Note di implementazione
+- **Determinismo**: `generation_date` è derivato dai dati (anno massimo nei periodi osservati), non dall'orario di esecuzione. Stesso input → stesso output, in conformità al principio 6 di `docs/REGOLE_SEGNALAZIONE.md`.
+- **Fail-closed**: in assenza di file o di campi obbligatori non viene emessa alcuna pista (nessun errore, nessuna inferenza).
+
 ## Licenza
 GNU Affero General Public License v3.0

rules/rules_v0.1.yaml

@@ -27,7 +27,7 @@ rules:
     condition: "same_cig_or_cup linked to >= threshold distinct subjects without explicit explanation in source"
     threshold: 2
     period: "full_dataset_coverage"
-    required_fields: ["cig_or_cup", "subject_id"]
+    required_fields: ["cig", "cup", "subject_id"]   # il motore richiede almeno uno tra cig/cup e un subject_id (vedi scripts/apply_rules.py)
     note: "Questo non dimostra alcun illecito. Indica solo una concentrazione che merita verifica."
 
   - id: REGOLA-004

templates/lead_template.md

@@ -1,3 +1,5 @@
+> Nota: template illustrativo. Il motore (`scripts/apply_rules.py`) genera il Markdown inline; questo file documenta lo schema obbligatorio definito in `docs/FORMATO_PISTA.md`.
+
 # {{ title }}
 
 **ID**: {{ id }}

tests/test_engine.py

@@ -0,0 +1,119 @@
+import json
+import sys
+from pathlib import Path
+
+import pandas as pd
+import yaml
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "scripts"))
+
+from apply_rules import (  # noqa: E402
+    apply_regola_001,
+    apply_regola_002,
+    apply_regola_003,
+    stable_id,
+    _derive_gen_date,
+    WHAT_CANNOT,
+    DISCLAIMER,
+)
+
+
+def _df(rows, cols):
+    return pd.DataFrame(rows, columns=cols)
+
+
+def test_regola_001_soglia():
+    rows = [
+        ["MARIO ROSSI", "E1", "2025", "inc", "a1"],
+        ["MARIO ROSSI", "E2", "2025", "inc", "a2"],
+        ["MARIO ROSSI", "E3", "2025", "inc", "a3"],
+        ["MARIO ROSSI", "E4", "2025", "inc", "a4"],
+        ["MARIO ROSSI", "E5", "2025", "inc", "a5"],
+    ]
+    df = _df(rows, ["person_name", "entity_id", "year"])
+    leads = apply_regola_001(df, 5, "same_calendar_year")
+    assert len(leads) == 1
+    assert leads[0]["rule_id"] == "REGOLA-001"
+    assert leads[0]["disclaimer"] == DISCLAIMER
+    assert leads[0]["what_cannot_be_claimed"] == WHAT_CANNOT
+
+
+def test_regola_001_sotto_soglia():
+    rows = [
+        ["MARIO ROSSI", "E1", "2025", "inc", "a1"],
+        ["MARIO ROSSI", "E2", "2025", "inc", "a2"],
+        ["MARIO ROSSI", "E3", "2025", "inc", "a3"],
+        ["MARIO ROSSI", "E4", "2025", "inc", "a4"],
+    ]
+    df = _df(rows, ["person_name", "entity_id", "year"])
+    assert apply_regola_001(df, 5, "same_calendar_year") == []
+
+
+def test_regola_001_fail_closed_colonne_mancanti():
+    df = _df([["X", "E1"]], ["person_name", "entity_id"])
+    assert apply_regola_001(df, 5, "same_calendar_year") == []
+
+
+def test_regola_002_diretti():
+    rows = [[f"AWARD", "ENT", f"2025-0{i}-01", "affidamento diretto", "s", f"r{i}"] for i in range(1, 9)]
+    df = _df(rows, ["awardee", "entity_id", "award_date", "procedure_type", "source_dataset", "source_record_id"])
+    leads = apply_regola_002(df, 8, "12_months_rolling")
+    assert len(leads) == 1
+    assert leads[0]["rule_id"] == "REGOLA-002"
+
+
+def test_regola_002_non_diretti():
+    rows = [[f"AWARD", "ENT", f"2025-0{i}-01", "gara ordinaria", "s", f"r{i}"] for i in range(1, 9)]
+    df = _df(rows, ["awardee", "entity_id", "award_date", "procedure_type", "source_dataset", "source_record_id"])
+    assert apply_regola_002(df, 8, "12_months_rolling") == []
+
+
+def test_regola_003_cig():
+    rows = [
+        ["CIG1", "SUB1", "s", "t1"],
+        ["CIG1", "SUB2", "s", "t2"],
+    ]
+    df = _df(rows, ["cig", "subject_id", "source_dataset", "source_record_id"])
+    leads = apply_regola_003(df, 2, "full_dataset_coverage")
+    assert len(leads) == 1
+    assert leads[0]["rule_id"] == "REGOLA-003"
+    assert leads[0]["period"] == "intero periodo coperto dal dataset"
+
+
+def test_regola_003_fail_closed_senza_cig():
+    df = _df([["SUB1", "s", "t1"]], ["subject_id", "source_dataset", "source_record_id"])
+    assert apply_regola_003(df, 2, "full_dataset_coverage") == []
+
+
+def test_determinismo_id_e_data():
+    rows = [
+        ["MARIO ROSSI", "E1", "2025", "inc", "a1"],
+        ["MARIO ROSSI", "E2", "2025", "inc", "a2"],
+        ["MARIO ROSSI", "E3", "2025", "inc", "a3"],
+        ["MARIO ROSSI", "E4", "2025", "inc", "a4"],
+        ["MARIO ROSSI", "E5", "2025", "inc", "a5"],
+    ]
+    df = _df(rows, ["person_name", "entity_id", "year"])
+    a = apply_regola_001(df, 5, "same_calendar_year")
+    b = apply_regola_001(df, 5, "same_calendar_year")
+    assert json.dumps(a, sort_keys=True) == json.dumps(b, sort_keys=True)
+    assert a[0]["generation_date"] == "2025-01-01"
+    assert a[0]["id"] == stable_id("REGOLA-001", "MARIO ROSSI|2025", "2025")
+
+
+def test_derive_gen_date_senza_anno():
+    leads = [{"period": "intero periodo coperto dal dataset"}]
+    assert _derive_gen_date(leads) == "0000-01-01"
+
+
+def test_derive_gen_date_max_anno():
+    leads = [{"period": "2024"}, {"period": "2025"}]
+    assert _derive_gen_date(leads) == "2025-01-01"
+
+
+def test_regola_004_disabilitata():
+    data = yaml.safe_load(
+        open(Path(__file__).resolve().parent.parent / "rules" / "rules_v0.1.yaml", encoding="utf-8")
+    )
+    r004 = next(r for r in data["rules"] if r["id"] == "REGOLA-004")
+    assert r004["enabled"] is False