fix(ci): ruff non pinnato tiene la CI rossa e blocca la pubblicazione delle immagini

[gzileni]

Sintomo

La CI è rossa su main da inizio agosto, e la conseguenza non è cosmetica:
le immagini su GHCR non vengono più pubblicate.

docker-publish.yml è gated sulla CI:

on:
  workflow_run:
    workflows: ["CI"]
    types: [completed]
    branches: [main]
jobs:
  publish:
    if: ${{ github.event.workflow_run.conclusion == 'success' }}

Catena verificata il 2026-09-03:

Passo	Esito
CI su main (a1b03eb)	failure — step ruff check .
docker-publish conseguente	skipped
ghcr.io/.../kg-api:latest (+ kg-ui, kg-mcp, kg-agents)	ancora da eab6c0b, 11 giugno 2026

Effetto concreto: il lavoro llama.cpp/OpenAI della PR #5 è su main da un
mese ma non è in nessuna immagine pubblicata. Chi fa docker compose -f docker-compose.ghcr.yml up ottiene il comportamento pre-#5 — solo Ollama —
senza alcun segnale che stia usando codice vecchio. È esattamente il tipo di
guasto che sembra un bug di configurazione per giorni.

Causa

Non è codice nuovo: il linter non è pinnato.

knowledge-graph-api/requirements.txt:38

ruff>=0.4.0

La CI risolve alla 0.16.1, che ha abilitato regole non attive quando la CI era
verde (giugno). Quelle regole illuminano codice preesistente.

Misurato con ruff==0.16.1 su worktree puliti:

Ref	Errori
a1b03eb (main, post PR #5)	21
eab6c0b (pre PR #5)	21, distribuzione identica per regola

Quindi la PR #5 è neutra sul lint: non ha rotto niente, ha solo avuto la
sfortuna di essere il primo push dopo che una nuova ruff era uscita.

Con ruff>=0.4.0 la CI è una funzione della data, non del codice: lo stesso
commit passa o fallisce a seconda di quando gira. È la proprietà che rende
inutile un gate.

I 21 rilievi

cd knowledge-graph-api && ruff check . — 5 auto-fixabili con --fix.

Regola	N	Dove
BLE001 blind except Exception	12	api/main.py (63, 72, 82), api/routes/graph.py:96, api/routes/ingest.py (38, 120, 193), api/routes/query.py:30, pipeline/extractor.py:149, pipeline/ingest.py:108, storage/redis_vector.py (69, 265)
I001 import non ordinati [*]	3	api/routes/ingest.py:3, storage/neo4j_graph.py:3, tests/conftest.py:3
B008 chiamata a File() nei default	2	api/routes/ingest.py (45, 75)
DTZ001 datetime() senza tzinfo	2	tests/test_ingest_json.py (48, 82)
RUF022 __all__ non ordinato [*]	1	models/__init__.py:7
ASYNC230 open() bloccante in funzione async	1	tests/test_ingest_json.py:26

Nota sulle BLE001: buona parte sono except Exception deliberati in
handler HTTP e in percorsi che devono degradare invece di propagare (health
check, ingest, keyword search). Non vanno "corretti" trasformandoli in eccezioni
strette se la semantica voluta è «qualunque cosa vada storta, degrada e logga» —
in quel caso l'# noqa: BLE001 con una riga di motivazione è la risposta
onesta, non un except (A, B, C) che dimentica il quarto caso.

Fix proposto

1. Pinnare il linter: ruff==0.16.1 in requirements.txt (o ~=0.16.0).
   Aggiornarlo diventa così un cambiamento deliberato e revisionabile, non un
   evento meteorologico.
2. Azzerare i 21 rilievi: ruff check . --fix per i 5 automatici; per le
   BLE001 decidere caso per caso fra eccezione stretta e # noqa motivato;
   B008 con il singleton a livello di modulo; DTZ001/ASYNC230 nei test
   sono correzioni banali.
3. Verificare che gli altri tre componenti (knowledge-graph-mcp,
   -agents, -ui) non abbiano lo stesso pin aperto: la CI li lint-a tutti, e
   basta uno per tenere rosso il gate.

Acceptance criteria

• ruff pinnato in tutti i requirements.txt/manifest che la CI installa.
• ruff check . verde in knowledge-graph-api (e negli altri componenti).
• CI verde su main.
• docker-publish riparte e ripubblica le 4 immagini; verificato che
  kg-api:latest contenga pipeline/llm/llamacpp_provider.py.
• pytest tests/ resta verde (baseline attuale: 32 passed).

Relazioni

• Blocca l'effetto pratico di feat(llm): provider OpenAI-compatibile di prima classe (llamacpp → openai, con alias) #6 (provider OpenAI-compatibile): finché il
  publish è skipped, nessun rename arriva in un'immagine.
• Sblocca l'uso del sidecar da
  limen, che punta
  KG__BASE_URL allo stack docker-compose.ghcr.yml e oggi riceverebbe
  l'immagine di giugno.