fix(vote-detail): risolvi --group-acronym contro le sigle reali del voto (#77)

Le sigle di ocd:siglaGruppo non coincidono con l'acronym di `groups list`
(AZ-PER-RE → APERRE, IV-CR → IVICRE, Misto disaggregato): il FILTER su una
sigla inesistente restituiva zero righe senza dire perché.

La sigla richiesta viene ora risolta contro quelle effettivamente presenti
nella votazione (query leggera), con confronto tollerante a maiuscole e
punteggiatura. Se non esiste: risultato vuoto + hint con le sigle reali e la
più simile. Nessuna mappatura hardcoded: il disallineamento è della fonte e
va risolto lì, il codice si limita a renderlo visibile.

Closes #77

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: aborruso

src/tools/vote-detail.test.ts

@@ -0,0 +1,75 @@
+import { describe, it, expect } from "vitest";
+import { resolveGroupAcronym, buildGroupAcronymHint } from "./vote-detail.js";
+
+// Sigle realmente presenti in una votazione di leg. 19 (vs19_456_018).
+const AVAILABLE = [
+  "FDI",
+  "M5S",
+  "LEGA",
+  "M-ALT",
+  "M-MIN",
+  "PD-IDP",
+  "FI-PPE",
+  "AVS",
+  "M-+EUR",
+  "APERRE",
+  "IVICRE",
+  "NM-M-C",
+];
+
+describe("resolveGroupAcronym", () => {
+  it("match esatto", () => {
+    expect(resolveGroupAcronym("FDI", AVAILABLE)).toBe("FDI");
+    expect(resolveGroupAcronym("FI-PPE", AVAILABLE)).toBe("FI-PPE");
+  });
+
+  it("ignora maiuscole/minuscole", () => {
+    expect(resolveGroupAcronym("fdi", AVAILABLE)).toBe("FDI");
+    expect(resolveGroupAcronym("Pd-Idp", AVAILABLE)).toBe("PD-IDP");
+  });
+
+  it("ignora la punteggiatura", () => {
+    expect(resolveGroupAcronym("PD IDP", AVAILABLE)).toBe("PD-IDP");
+    expect(resolveGroupAcronym("nmmc", AVAILABLE)).toBe("NM-M-C");
+  });
+
+  it("null sulle sigle di groups list non derivabili da una regola", () => {
+    // Sono i casi che motivano l'hint: nessuna normalizzazione le riconcilia.
+    expect(resolveGroupAcronym("AZ-PER-RE", AVAILABLE)).toBeNull();
+    expect(resolveGroupAcronym("IV-CR", AVAILABLE)).toBeNull();
+    expect(resolveGroupAcronym("MISTO", AVAILABLE)).toBeNull();
+  });
+
+  it("null su sigla inesistente", () => {
+    expect(resolveGroupAcronym("XYZ", AVAILABLE)).toBeNull();
+  });
+});
+
+describe("buildGroupAcronymHint", () => {
+  it("suggerisce la sigla più simile e elenca quelle presenti", () => {
+    const h = buildGroupAcronymHint("AZ-PER-RE", AVAILABLE);
+    expect(h).toContain('Nessun gruppo con sigla "AZ-PER-RE"');
+    expect(h).toContain('Forse cercavi "APERRE"');
+    expect(h).toContain("IVICRE");
+  });
+
+  it("suggerisce IVICRE per IV-CR", () => {
+    expect(buildGroupAcronymHint("IV-CR", AVAILABLE)).toContain('Forse cercavi "IVICRE"');
+  });
+
+  it("spiega che il Misto è disaggregato", () => {
+    const h = buildGroupAcronymHint("MISTO", AVAILABLE);
+    expect(h).toContain("Misto");
+    expect(h).toContain("M-ALT");
+    // Nessuna componente somiglia a "MISTO": meglio nessun suggerimento che uno a caso.
+    expect(h).not.toContain("Forse cercavi");
+  });
+
+  it("non suggerisce nulla su una sigla senza affinità", () => {
+    expect(buildGroupAcronymHint("XYZ", AVAILABLE)).not.toContain("Forse cercavi");
+  });
+
+  it("votazione senza sigle: dice che il filtro non è applicabile", () => {
+    expect(buildGroupAcronymHint("FDI", [])).toContain("non è applicabile");
+  });
+});

src/tools/vote-detail.ts

@@ -13,7 +13,9 @@ const inputSchema = z.object({
   groupAcronym: z
     .string()
     .optional()
-    .describe("Filtra per sigla gruppo (es. 'FDI', 'PD-IDP', 'M5S'). Case-sensitive."),
+    .describe(
+      "Filtra per sigla gruppo (es. 'FDI', 'M5S', 'APERRE'). Le sigle sono quelle del dataset votazioni, che NON sempre coincidono con l'acronym di `groups list` (es. AZ-PER-RE → APERRE, IV-CR → IVICRE) e in cui il gruppo Misto è disaggregato nelle sue componenti (M-ALT, M-MIN, …). Maiuscole/minuscole e punteggiatura sono irrilevanti; se la sigla non esiste in quella votazione il risultato è vuoto con l'elenco delle sigle presenti.",
+    ),
   voteType: z
     .enum(["Favorevole", "Contrario", "Astensione", "Non ha votato"])
     .optional()
@@ -29,6 +31,84 @@ function stripLegLabel(label: string): string {
 
 const columns = ["deputy_uri", "deputy_name", "vote", "group_uri", "group_acronym", "html_url"];
 
+// Le sigle di `ocd:siglaGruppo` (dataset votazioni) non coincidono con
+// l'acronym di `groups list`: AZ-PER-RE → APERRE, IV-CR → IVICRE, e il Misto è
+// disaggregato per componente. Il confronto ignora quindi maiuscole e
+// punteggiatura, ma le differenze restanti non sono derivabili da una regola:
+// per quelle si mostra l'elenco delle sigle realmente presenti nel voto.
+function normalizeAcronym(s: string): string {
+  return s.toUpperCase().replace(/[^A-Z0-9]/g, "");
+}
+
+/** Sigla del dataset corrispondente a quella richiesta, o null se nessuna. */
+export function resolveGroupAcronym(requested: string, available: string[]): string | null {
+  const exact = available.find((a) => a === requested);
+  if (exact) return exact;
+  const ci = available.find((a) => a.toUpperCase() === requested.toUpperCase());
+  if (ci) return ci;
+  const norm = normalizeAcronym(requested);
+  return available.find((a) => normalizeAcronym(a) === norm) ?? null;
+}
+
+/** Somiglianza di Dice sui bigrammi: ordina i suggerimenti, non decide il match. */
+function similarity(a: string, b: string): number {
+  const bigrams = (s: string) => {
+    const out: string[] = [];
+    for (let i = 0; i < s.length - 1; i++) out.push(s.slice(i, i + 2));
+    return out;
+  };
+  const A = bigrams(a);
+  const B = bigrams(b);
+  if (A.length === 0 || B.length === 0) return a === b ? 1 : 0;
+  const pool = [...B];
+  let hits = 0;
+  for (const g of A) {
+    const i = pool.indexOf(g);
+    if (i >= 0) {
+      hits++;
+      pool.splice(i, 1);
+    }
+  }
+  return (2 * hits) / (A.length + B.length);
+}
+
+/** Nota mostrata quando la sigla richiesta non esiste in quella votazione. */
+export function buildGroupAcronymHint(requested: string, available: string[]): string {
+  if (available.length === 0) {
+    return `Nessuna sigla di gruppo registrata in questa votazione: il filtro --group-acronym non è applicabile.`;
+  }
+  const norm = normalizeAcronym(requested);
+  const ranked = [...available].sort(
+    (x, y) => similarity(norm, normalizeAcronym(y)) - similarity(norm, normalizeAcronym(x)),
+  );
+  const best = ranked[0];
+  const parts = [
+    `Nessun gruppo con sigla "${requested}" in questa votazione.`,
+    `Le sigle del dataset votazioni non coincidono sempre con l'acronym di 'groups list' (es. AZ-PER-RE → APERRE, IV-CR → IVICRE).`,
+  ];
+  if (similarity(norm, normalizeAcronym(best)) >= 0.4) {
+    parts.push(`Forse cercavi "${best}".`);
+  }
+  parts.push(`Sigle presenti in questa votazione: ${ranked.join(", ")}.`);
+  if (available.some((a) => /^M-/.test(a))) {
+    parts.push(`Il gruppo Misto è disaggregato nelle sue componenti (le sigle "M-…"): non esiste una riga "MISTO".`);
+  }
+  return parts.join(" ");
+}
+
+/** Sigle di gruppo effettivamente presenti nella votazione (query leggera). */
+async function fetchVoteAcronyms(voteUri: string): Promise<string[]> {
+  const query = `${OCD_PREFIXES}
+SELECT DISTINCT ?siglaGruppo
+WHERE {
+  ?v a ocd:voto .
+  ?v ocd:rif_votazione <${voteUri}> .
+  ?v ocd:siglaGruppo ?siglaGruppo .
+}`;
+  const raw = flattenBindings(await cdQuery(query));
+  return raw.map((r) => r.siglaGruppo ?? "").filter((s) => s !== "");
+}
+
 export const voteDetailTool: Tool<typeof inputSchema> = {
   name: "vote-detail",
   description:
@@ -39,10 +119,21 @@ export const voteDetailTool: Tool<typeof inputSchema> = {
     "italianparliament vote-detail show --vote-uri http://dati.camera.it/ocd/votazione.rdf/vs18_100_005 --format jsonl",
     "italianparliament vote-detail show --vote-uri http://dati.camera.it/ocd/votazione.rdf/vs19_010_003 --limit 50",
     "italianparliament vote-detail show --vote-uri http://dati.camera.it/ocd/votazione.rdf/vs19_641_046 --group-acronym FDI --vote-type Contrario",
+    "italianparliament vote-detail show --vote-uri http://dati.camera.it/ocd/votazione.rdf/vs19_456_018 --group-acronym APERRE",
   ],
   async execute(input) {
     const filters: string[] = [];
-    if (input.groupAcronym) filters.push(`?v ocd:siglaGruppo ?_sg . FILTER(STR(?_sg) = "${input.groupAcronym}")`);
+    if (input.groupAcronym) {
+      // La sigla richiesta va risolta contro quelle realmente presenti nel voto,
+      // altrimenti un FILTER su una sigla inesistente restituirebbe zero righe
+      // senza dire perché (issue #77).
+      const available = await fetchVoteAcronyms(input.voteUri);
+      const resolved = resolveGroupAcronym(input.groupAcronym, available);
+      if (!resolved) {
+        return { rows: [], columns, hint: buildGroupAcronymHint(input.groupAcronym, available) };
+      }
+      filters.push(`?v ocd:siglaGruppo ?_sg . FILTER(STR(?_sg) = "${resolved}")`);
+    }
     if (input.voteType) filters.push(`FILTER(?type = "${input.voteType}")`);
 
     const query = `${OCD_PREFIXES}