fix camera keyword html entities (#64)

Author: aborruso

LOG.md

@@ -1,5 +1,9 @@
 # LOG
 
+## 2026-07-13
+
+- **fix keyword Camera con entità HTML** — `bills --keyword` e `bill-progress --uri/--branch C --keyword` ora cercano anche la variante HTML-escaped della keyword (`criminalità` → `criminalità`). Il LOD Camera salva alcuni `rdfs:label`/`dc:title` con entità HTML ma la CLI decodifica l'output: prima una ricerca sul testo visibile (`--keyword "criminalità"`) non trovava atti il cui titolo mostrato contiene `criminalità organizzata`; funzionavano solo workaround come `criminalit` o `criminalità`. Aggiunto helper condiviso `htmlEntityKeywordVariants`, test di regressione su `ac19_2696`, build/tsc/test completi verdi (161/161).
+
 ## 2026-07-12
 
 - **v0.25.1** — release patch. Un solo fix funzionale dopo la v0.25.0: **`senato-votes --ddl-uri` ora deriva la legislatura dal DDL** invece di applicare il default 19 come filtro rigido (#60, PR #61). Prima, passando solo `--ddl-uri` di un provvedimento di legislatura ≠ 19, il comando dava un **falso negativo silenzioso** ("Nessuna votazione trovata"): un giornalista che cercava un voto Senato storico (es. il decreto lockdown DL 19/2020, S.1811, leg.18) non trovava nulla e poteva concludere erroneamente che il dato mancasse. Ora la legislatura effettiva è letta da `osr:legislatura` del DDL (l'URI `dati.senato.it/ddl/{N}` non la codifica) e usata in tutte le query — allineando il comportamento a `votes --bill-code` (Camera), che non vincola la legislatura. Aggiunti alla scoperta anche description e esempio `--help` con un DDL storico, e nota nella skill. Emerso dal run news-driven `docs/news-agent/2026-07-11_18-11.md` (era l'unico gap reale con impatto; gli altri due rilievi erano assenze source-side già documentate nel wiki, non gap CLI). Contestualmente rimosso dalla CI il job `live_integration` (sempre rosso dai runner GitHub: gli endpoint LOD bloccano gli IP CI — zero segnale; il testing live resta affidabile in locale). 43 tool invariati, 159/159 test verdi in locale.

src/core/html-entity-variants.ts

@@ -0,0 +1,38 @@
+const HTML_ENTITY_BY_CHAR: Record<string, string> = {
+  '"': "&quot;",
+  "'": "&apos;",
+  "&": "&amp;",
+  "<": "&lt;",
+  ">": "&gt;",
+  "\u2019": "&rsquo;",
+  "\u2018": "&lsquo;",
+  "\u201d": "&rdquo;",
+  "\u201c": "&ldquo;",
+  "\u2013": "&ndash;",
+  "\u2014": "&mdash;",
+  "\u2026": "&hellip;",
+  "\u20ac": "&euro;",
+  "\u00ab": "&laquo;",
+  "\u00bb": "&raquo;",
+  "\u00e0": "&agrave;",
+  "\u00e8": "&egrave;",
+  "\u00e9": "&eacute;",
+  "\u00ec": "&igrave;",
+  "\u00f2": "&ograve;",
+  "\u00f9": "&ugrave;",
+};
+
+const HTML_ENTITY_CHARS = /["'&<>\u2018\u2019\u201c\u201d\u2013\u2014\u2026\u20ac\u00ab\u00bb\u00e0\u00e8\u00e9\u00ec\u00f2\u00f9]/g;
+
+/**
+ * Camera LOD often stores title/label literals with HTML entities
+ * (e.g. `criminalit&agrave;`) while CLI users search the decoded text
+ * (`criminalità`). Return both forms so SPARQL filters can match raw data.
+ */
+export function htmlEntityKeywordVariants(keyword: string): string[] {
+  const htmlEncoded = keyword.replace(
+    HTML_ENTITY_CHARS,
+    (char) => HTML_ENTITY_BY_CHAR[char] ?? char,
+  );
+  return [...new Set([keyword, htmlEncoded])];
+}

src/tools/bill-progress.ts

@@ -3,6 +3,7 @@ import { snQuery, cdQuery } from "../core/client.js";
 import { OSR_PREFIXES, OCD_PREFIXES } from "../core/prefixes.js";
 import { flattenBindings } from "../core/flatten.js";
 import { decodeHtml } from "../core/decode-html.js";
+import { htmlEntityKeywordVariants } from "../core/html-entity-variants.js";
 import { ddlRssUrl } from "../core/html-url.js";
 import { currentLegislature } from "../core/current-legislature.js";
 import type { Tool } from "./types.js";
@@ -162,7 +163,9 @@ export const billProgressTool: Tool<typeof inputSchema> = {
     }
     if (input.keyword) {
       filters.push(
-        `FILTER(CONTAINS(LCASE(STR(?titolo)), LCASE(${sparqlStringLiteral(input.keyword)})))`,
+        `FILTER(${htmlEntityKeywordVariants(input.keyword)
+          .map((variant) => `CONTAINS(LCASE(STR(?titolo)), LCASE(${sparqlStringLiteral(variant)}))`)
+          .join(" || ")})`,
       );
     }
     if (input.number) {
@@ -254,7 +257,9 @@ async function cameraIterTimeline(
   const filters: string[] = [];
   if (opts.keyword) {
     filters.push(
-      `FILTER(BOUND(?titolo) && CONTAINS(LCASE(STR(?titolo)), LCASE(${sparqlStringLiteral(opts.keyword)})))`,
+      `FILTER(BOUND(?titolo) && (${htmlEntityKeywordVariants(opts.keyword)
+        .map((variant) => `CONTAINS(LCASE(STR(?titolo)), LCASE(${sparqlStringLiteral(variant)}))`)
+        .join(" || ")}))`,
     );
   }
   if (opts.dateFrom) {

src/tools/bills.ts

@@ -3,6 +3,7 @@ import { cdQuery } from "../core/client.js";
 import { flattenBindings } from "../core/flatten.js";
 import { OCD_PREFIXES } from "../core/prefixes.js";
 import { decodeHtml } from "../core/decode-html.js";
+import { htmlEntityKeywordVariants } from "../core/html-entity-variants.js";
 import { actHtmlUrl } from "../core/html-url.js";
 import type { Tool } from "./types.js";
 
@@ -85,7 +86,12 @@ export const billsTool: Tool<typeof inputSchema> = {
         : "";
     const keywordFilter =
       input.keyword !== undefined
-        ? `FILTER(CONTAINS(LCASE(STR(?label)), LCASE("${sparqlEscape(input.keyword)}")) || CONTAINS(LCASE(STR(?title)), LCASE("${sparqlEscape(input.keyword)}")))`
+        ? `FILTER(${htmlEntityKeywordVariants(input.keyword)
+            .map(
+              (variant) =>
+                `(CONTAINS(LCASE(STR(?label)), LCASE("${sparqlEscape(variant)}")) || CONTAINS(LCASE(STR(?title)), LCASE("${sparqlEscape(variant)}")))`,
+            )
+            .join(" || ")})`
         : "";
     const typeFilter =
       input.type !== undefined

src/tools/tools.test.ts

@@ -113,6 +113,20 @@ describe("Camera tools", () => {
     expect(result.rows[0]).toHaveProperty("type");
   }, 30000);
 
+  it("bills: keyword matches decoded HTML entities in Camera titles", async () => {
+    const result = await billsTool.execute({
+      legislature: 19,
+      keyword: "criminalità",
+      limit: 10,
+      offset: 0,
+    });
+    expect(
+      result.rows.some(
+        (r) => r.uri === "http://dati.camera.it/ocd/attocamera.rdf/ac19_2696",
+      ),
+    ).toBe(true);
+  }, 30000);
+
   it("votes: returns votes for legislature 19", async () => {
     const result = await votesTool.execute({ legislature: 19, limit: 3, offset: 0 });
     expect(result.rows.length).toBe(3);
@@ -554,6 +568,21 @@ describe("Senato tools", () => {
     expect(first.phase).toBe("C.302");
   }, 30000);
 
+  it("bill-progress: Camera keyword matches decoded HTML entities in atto titles", async () => {
+    const result = await billProgressTool.execute({
+      uri: "http://dati.camera.it/ocd/attocamera.rdf/ac19_2696",
+      keyword: "criminalità",
+      limit: 10,
+      offset: 0,
+    });
+    expect(result.rows.length).toBeGreaterThan(0);
+    expect(
+      result.rows.every(
+        (r) => r.ddl_uri === "http://dati.camera.it/ocd/attocamera.rdf/ac19_2696",
+      ),
+    ).toBe(true);
+  }, 30000);
+
   it("bill-progress: --number + --branch C returns the Camera iter timeline (#41)", async () => {
     // dl Covid Camera 2020: --number 2617 --branch C --legislature 18 deve dare
     // la timeline dell'atto Camera (più stati datati), non il record di rimando