Tracks Italian law changes via the Normattiva API and records each modification as a git commit.

Concern Location

Source code branch main

Data branch history

OpenNorme source explore

OpenNorme site gh-pages

Provisional DL dl/<codice>

Provisional RDL rdl/<codice>

Provisional DLL dll/<codice>

Provisional DLCPS dlcps/<codice>

Checkpoint file progress-rs.json

One-time setup

Install Rust (skip if already present):

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y . "$HOME/.cargo/env"

Then check out this branch:

cd /path/to/italian-laws-history git checkout main

Build

cargo build --release

Binary: ./target/release/italian-laws-history

For iteration, cargo build produces a debug build that compiles faster.

The binary writes data to the history and dl/<codice> (and friends) branches in OUTPUT_REPO (defaults to the current directory), and persists state to progress-rs.json.

./target/release/italian-laws-history --ci

Start from a specific date

./target/release/italian-laws-history --ci 2024-12-01

Reprocess everything from scratch

./target/release/italian-laws-history --ci --force 1861-01-01

Interactive TUI dashboard (no --ci)

./target/release/italian-laws-history 2024-12-01

q or Ctrl-C to quit

The TUI shows a list of recently-discovered acts, a decade chart, a reference-count distribution, a type-share gauge, a scrolling log, and a status line. Falls back to the plain stdout logger automatically when the terminal is too small (< 40×10).

./target/release/italian-laws-history --ci --perf 2024-12-01

Produces trace-<timestamp>.json — open in chrome://tracing

Output to a separate directory (recommended for testing)

The binary's writes land on history / dl/... branches, which by default live in the same repo as your main source code. To keep them isolated, point OUTPUT_REPO at a separate directory:

mkdir -p /tmp/laws-data && cd /tmp/laws-data && git init -q git config user.email "you@example.com" git config user.name "Your Name"

cd /path/to/italian-laws-history OUTPUT_REPO=/tmp/laws-data ./target/release/italian-laws-history --ci 2024-12-01

Inspect:

cd /tmp/laws-data git branch -a git log history --oneline | head

All flags

./target/release/italian-laws-history --help

[SINCE_DATE] — optional YYYY-MM-DD, overrides the checkpoint

--force — ignore checkpoint, reprocess everything

--ci / --headless — no TUI, plain stdout logger

--perf — emit trace-*.json

-V / --version, -h / --help

Environment overrides

Variable Default

OUTPUT_REPO ./

NORMATTIVA_API_BASE https://api.normattiva.it/t/normattiva.api/bff-opendata/v1

NORMATTIVA_API_TOKEN (empty — most endpoints are public)

GIT_AUTHOR_NAME GU Bot

GIT_AUTHOR_EMAIL gu-bot@example.org

BATCH_SIZE 10

CONCURRENCY 3

MIN_TIME_MS 300

MAX_RETRIES 5

CACHE_TTL_SEC 3600

CHECKPOINT_FILE progress-rs.json

GITHUB_REPO $GITHUB_REPOSITORY (Actions) or unset — skip PRs

Stopping safely

Ctrl-C is safe at any time. The checkpoint is written atomically after each search page (and on interrupt or month end), so the next run resumes from where it stopped (use the same command without --force). A kill mid-page may re-fetch up to one page of acts.

Italian law has several act types that are provisional — they enter into force immediately but only become permanent after a separate ratification. The binary commits each one to a dedicated branch, opens a GitHub PR into history (when GITHUB_REPO/GITHUB_REPOSITORY and GH_TOKEN are set), and merges the branch into history once its lifecycle resolves. Conversion and sanatoria leave the PR merged; decadenza still merges, then comments the due date that expired:

Acts with no automatic decadenza wait indefinitely on their branch until either a ratifying law is published or Normattiva flags them as abrogated.

.github/workflows/daily-scrape.yml runs the binary daily at 12:00 UTC with --ci. It fetches only the tip of history. The progress-rs.json checkpoint is committed back to main.

.github/workflows/pages.yml checks out explore, reads that checkpoint from main, and reads the tip of history (commit-index.tsv plus the current texts). It publishes dist/ to gh-pages.

Digesto, the assistant in OpenNorme (explore), is inspired by ClippyJS (clippyjs), a rewrite of Clippy.JS. The sprite animator, action queue, and speech balloon follow that agent model. Digesto's drawings and copy are original to this project. Clippy and the other Office assistants remain Microsoft's.

The scraper and the other source on main, and OpenNorme on explore, are MIT. The license badge GitHub shows for this repository refers to that code.

The law texts on history, and the data/ files built from them onto gh-pages, are Normattiva open data from the Istituto Poligrafico e Zecca dello Stato, under CC BY 4.0. history carries the attribution in NOTICE. Keep it with any redistribution of those texts:

Fonte: Normattiva (https://www.normattiva.it), Istituto Poligrafico e Zecca dello Stato, licenza CC BY 4.0. Testo non autentico e gratuito: l'unico testo ufficiale è quello pubblicato sulla Gazzetta Ufficiale a mezzo stampa.