feat(amendments): fallback bulk AKN GitHub + proponenti dal testo AKN

[aborruso]

Cosa fa

Implementa la priorità P1 dell'analisi fonti non-LOD (#45): il tool amendments usa il bulk AKN GitHub del Senato (SenatoDellaRepubblica/AkomaNtosoBulkData, CC BY 4.0, senza WAF → funziona in CLI e Worker).

1. akn_xml_url su ogni riga LOD — conversione osr:URLTestoXml → URL raw (pura sostituzione di stringa, osr:flagCommissione decide emend/ vs emendc/): testo machine-readable scaricabile con un curl.
2. Fallback automatico — con ddlUri e LOD vuoto, listing di emend/+emendc/ via endpoint JSON web-UI GitHub, righe source=akn. Rete di sicurezza contro la freschezza intermittente del LOD.
3. withProponents / --with-proponents — primo firmatario e cofirmatari (con URI persona) dal testo AKN: il proponente NON è nel LOD (amendments (Senato): aggiungere il proponente via parsing AKN (simmetria con camera-amendments) #30). Fetch puntuali, concorrenza 4, mai bulk.

Valore giornalistico

Chi firma gli emendamenti di un provvedimento — finora dietro WAF, recuperabile solo a mano col browser — esce ora da un comando: verificato il caso wiki (em. 1.30 ddl/56260 → Bartolomeo Amidei + 5) e il Piano Casa (proponenti da entrambe le sedi).

Scoperta in corsa

Il dataset osr:Emendamento del LOD si è riallineato tra il 7 e il 10 luglio (Piano Casa 0→799, match esatto col bulk 400+399): il claim "fermo ad ago 2024" è superato e rimosso da description/emptyHint. Documentata nel wiki anche la trappola nuova: dataPresentazione dei DDL recenti ora tipizzata xsd:string (la query cutoff tipizzata sottoconta).

Note tecniche

• src/core/akn.ts Worker-compatible (solo fetch nativo); listing troncato a 1000 gestito via totalCount con errore esplicito su finestra irraggiungibile (no cap silenziosi); forma payload validata con errore esplicito se GitHub cambia l'endpoint (non documentato).
• Parser AKN a regex mirate (niente parser XML nel bundle Worker); gestite le due varianti markup (Assemblea: testo diretto; Commissione: nome in an:span; preferito TLCPerson@showAs col nome completo); file stub vuoti della fonte → campi vuoti, non errore.

Test

• +10 unit (src/core/akn.test.ts, offline) e +3 integrazione; suite 114/114 verdi, tsc pulito.
• Verifica live CLI: ddl/60233 (LOD fresco + proponenti), ddl/56260 (regressione + proponenti commissione), DDL inesistente (hint doppia-fonte).
• Resta da verificare la raggiungibilità di GitHub dal Worker post-deploy (Verificare raggiungibilità di documenti.camera.it dal Worker Cloudflare (camera-amendments) #28-like, annotato in Integrare i bulk data Akoma Ntoso del Senato (GitHub) come fonte complementare #45).

Closes #38, closes #30. Rif. #45.

🤖 Generated with Claude Code

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[greptile-apps]

Greptile Summary

This PR implements AKN bulk data integration for the amendments tool, using the Senato's GitHub repository (SenatoDellaRepubblica/AkomaNtosoBulkData, WAF-free) as a fallback when the LOD is stale and as the source for proponent data not available in the LOD. Issues raised in the previous review round (XML attribute ordering in regex, stale internal comment) have been addressed.

• src/core/akn.ts: New Worker-compatible module with listAknDir (GitHub web-UI JSON endpoint, explicit error on format change, sorted for determinism), parseAknAmendment (two-pass attribute extraction), fetchAknFile, and mapLimit (concurrency-limited async map preserving order).
• src/tools/amendments.ts: Every LOD row now carries akn_xml_url; when the LOD returns empty with ddlUri the tool falls back to the AKN bulk listing; withProponents fetches individual XML files with concurrency 4, an all-failures guard detects network outages vs. legitimate stub files, and truncation beyond the 1000-item GitHub listing cap is caught with explicit errors.
• Test coverage: 10 new unit tests (offline) and 3 new integration tests bring the suite to 114/114 green.

Confidence Score: 5/5

Safe to merge: new code is well-isolated, all edge cases are handled explicitly, and previous review concerns have been addressed.

The two core additions — listAknDir/parseAknAmendment in akn.ts and the dual-source orchestration in amendments.ts — handle their edge cases explicitly: format changes on the undocumented GitHub endpoint throw instead of returning a silent empty, the 1000-item listing truncation guard prevents incorrect pagination, and the all-failures check in enrichProponents distinguishes a network outage from legitimate empty stub files. No silent failure paths remain.

No files require special attention.

Important Files Changed

Filename	Overview
src/core/akn.ts	New module: AKN bulk data helpers (aknAttoPath, listAknDir, parseAknAmendment, mapLimit, fetchAknFile). Two-pass attribute extraction addresses previous review concerns; listing sorted for determinism; explicit errors on format/truncation changes.
src/tools/amendments.ts	Extends the amendments tool with akn_xml_url on every LOD row, automatic fallback to AKN bulk when LOD is empty with ddlUri, and withProponents enrichment; truncation guard and all-failures detection are correctly implemented.
src/core/akn.test.ts	New offline unit tests covering path construction, URL conversion, AKN parsing (incl. attribute-order inversion regression), deduplication, and mapLimit concurrency semantics.
src/tools/tools.test.ts	Adds integration tests for akn_xml_url presence, AKN fallback with hint, withProponents extraction, limit guard, all-failures detection, and checkAknTruncation variants (online + offline).
src/cli.ts	Adds --with-proponents boolean flag to amendments list command, correctly wired to withProponents input parameter.

_{Reviews (8): Last reviewed commit: "fix(amendments): hint distinto per pagin..." | Re-trigger Greptile}

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 7 comments.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 6 comments.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

src/tools/amendments.ts:169

• withProponents esegue un fetch per emendamento, ma al momento limit può arrivare a 1000: basta un uso “distratto” (es. --with-proponents senza abbassare --limit) per innescare centinaia/migliaia di richieste HTTP, con alta probabilità di timeout/rate limit (specie nel Worker). Suggerirei di imporre un cap (o un errore esplicito) quando withProponents è true e limit supera una soglia ragionevole (es. 100), lasciando invariato il caso senza proponenti.

  async execute(input) {
    // amendments interroga solo l'endpoint Senato: un ddlUri della Camera
    // passerebbe il FILTER senza match, restituendo un CSV vuoto che si può
    // scambiare per "nessun emendamento". In realtà gli emendamenti della
    // Camera NON esistono come entità nel LOD OCD (nessuna classe emendamento):

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated no new comments.