Integrazione CI/CD

Zenzic è pronto all'automazione. Il flag --format json e l'opzione --save espongono output machine-readable che qualsiasi sistema CI/CD può consumare per pilotare badge dinamici, quality gate e rilevamento delle regressioni.

---

Output JSON

Ogni comando di controllo supporta --format json:

# Report machine-readable per tutti i controlli
zenzic check all --format json

# Punteggio machine-readable con dettaglio per controllo
zenzic score --format json

zenzic check all --format json

{
  "links":         ["guides/setup.md:12 — Link target 'install.md' not found"],
  "orphans":       ["old-page.md"],
  "snippets":      [{"file": "api/ref.md", "line": 5, "message": "Snippet target not found"}],
  "placeholders":  [{"file": "index.md", "line": 1, "issue": "TODO", "detail": "Fix this"}],
  "unused_assets": ["images/old-logo.png"],
  "references":    [],
  "nav_contract":  []
}

zenzic score --format json

{
  "project": "zenzic",
  "score": 100,
  "threshold": 0,
  "status": "success",
  "timestamp": "2026-03-24T12:00:00+00:00",
  "categories": [
    {"name": "links",        "weight": 0.35, "issues": 0, "category_score": 1.0, "contribution": 0.35},
    {"name": "orphans",      "weight": 0.20, "issues": 0, "category_score": 1.0, "contribution": 0.20},
    {"name": "snippets",     "weight": 0.20, "issues": 0, "category_score": 1.0, "contribution": 0.20},
    {"name": "placeholders", "weight": 0.15, "issues": 0, "category_score": 1.0, "contribution": 0.10}
  ]
}

Comandi singoli (check links, check orphans, ecc.)

Ogni comando di controllo singolo restituisce una struttura findings uniforme:

{
  "findings": [
    {"rel_path": "guides/setup.md", "line_no": 42, "code": "BROKEN_LINK", "severity": "error", "message": "Link target 'install.md' not found"}
  ],
  "summary": {
    "errors": 1, "warnings": 0, "info": 0,
    "security_incidents": 0, "security_breaches": 0,
    "elapsed_seconds": 0.042
  }
}

I codici di uscita sono preservati in modalità JSON: exit 0 quando vengono trovati solo warning, exit 1 in caso di errori (o warning con --strict), exit 2 per violazioni Shield, exit 3 per Blood Sentinel — lo stesso contratto dell'output da terminale.

---

GitHub Actions: Gate Zenzic Shield

L'integrazione più semplice — blocca la build a qualsiasi errore di documentazione.

uvx (zero-setup)

Nessun setup Python richiesto. uvx scarica ed esegue Zenzic in un ambiente temporaneo ad ogni esecuzione. Ideale per repository documentazione-only o team che non hanno altrimenti bisogno di Python in CI:

# .github/workflows/docs.yml
name: Qualità Documentazione

on:
  push:
    branches: [main]
    paths: ['docs/**', 'mkdocs.yml']

jobs:
  zenzic:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Lint documentazione
        run: uvx --pre zenzic check all --strict

      - name: Controllo riferimenti e Shield
        run: uvx --pre zenzic check references

astral-sh/setup-uv (versione fissata)

Usa astral-sh/setup-uv quando hai bisogno di una versione Zenzic fissata, installazioni più veloci (cache wheel), o quando il progetto usa già uv per la gestione delle dipendenze:

# .github/workflows/docs.yml
name: Qualità Documentazione

on:
  push:
    branches: [main]
    paths: ['docs/**', 'mkdocs.yml']

jobs:
  zenzic:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Setup uv
        uses: astral-sh/setup-uv@v6
        with:
          enable-cache: true

      - name: Lint documentazione
        run: uvx --pre zenzic check all --strict

      - name: Controllo riferimenti e Shield
        run: uvx --pre zenzic check references

L'opzione enable-cache: true mantiene la cache degli strumenti uv tra le esecuzioni, eliminando il download da PyPI ad ogni push.

L'exit code 2 indica che una credenziale è stata rilevata in un URL di riferimento. L'exit code 3 indica che un link risolve a un percorso di sistema OS (Blood Sentinel). Entrambi richiedono indagine immediata — ruota le credenziali esposte e rimuovi il link incriminato.

---

GitHub Actions: Badge Score Dinamico

Questo workflow legge lo snapshot .zenzic-score.json e pubblica il punteggio live su un endpoint Shields.io tramite GitHub Gist, mantenendo il badge aggiornato ad ogni push.

# .github/workflows/zenzic-badge.yml
name: Badge Zenzic Score

on:
  push:
branches: [main]

jobs:
  score:
runs-on: ubuntu-latest
steps:
  - uses: actions/checkout@v6

  - name: 🛡️ Calcola Zenzic Score
    id: zenzic_step
    run: |
      uvx --pre zenzic score --save   # soglia letta da fail_under in zenzic.toml
      SCORE=$(jq '.score' .zenzic-score.json)
      echo "SCORE=$SCORE" >> "$GITHUB_OUTPUT"

  - name: 🔄 Aggiorna Gist per Badge
    uses: Schneegans/dynamic-badges-[email protected]
    with:
      auth: ${{ secrets.GIST_SECRET }}
      gistID: ${{ secrets.ZENZIC_GIST_ID }}
      filename: zenzic-score.json
      label: "🛡️ zenzic score"
      message: "${{ steps.zenzic_step.outputs.SCORE }}/100"
      valColorRange: ${{ steps.zenzic_step.outputs.SCORE }}
      maxColorRange: 100
      minColorRange: 0

Passi di configurazione:

1. Crea un GitHub Gist (pubblico o segreto).
2. Crea un Personal Access Token con scope gist e salvalo come GIST_SECRET nei segreti del repository.
3. Salva l'ID del tuo Gist (l'esadecimale lungo nell'URL) come ZENZIC_GIST_ID nei segreti del repository.
4. Aggiungi l'URL del badge dinamico al tuo README.md:

[![Zenzic Score](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/<user>/<gist-id>/raw/zenzic-score.json)](https://github.com/PythonWoods/zenzic)

Nota: valColorRange / maxColorRange / minColorRange producono un gradiente verde→giallo→rosso basato sul valore del punteggio. jq è preinstallato su tutti i runner GitHub-hosted.

---

Rilevamento Regressioni

zenzic diff confronta il punteggio corrente con il baseline .zenzic-score.json salvato:

- name: Rileva regressione del punteggio
  run: |
    uvx --pre zenzic score --save         # aggiorna snapshot
    uvx --pre zenzic diff --threshold 5   # fallisce se il punteggio scende > 5 punti

Combina con le branch protection rules per bloccare i merge che degradano la qualità della documentazione.

---

Codici di Uscita

Codice	Significato	Azione badge
0	Tutti i controlli superati	Mantieni il badge verde
1	Uno o più controlli falliti	Imposta il badge a failing / ef4444
2	Zenzic Shield: credenziale rilevata	Ruota la credenziale immediatamente
3	Blood Sentinel: path traversal rilevato	Rimuovi il link incriminato immediatamente

Per il riferimento completo dei badge pronti all'uso, vedi Badge Ufficiali.