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

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:

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:

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.

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.