Sentinel Gate Locale

Non debuggare l'output della build. Correggi i sorgenti prima che la build inizi.

Un errore di documentazione scoperto in CI significa una pipeline fallita, un cambio di contesto e un minuto di build sprecato. Scoperto prima della build, è solo una correzione di una riga.

Il pattern Sentinel Gate chiude il gap: Zenzic viene eseguito come pre-step obbligatorio, bloccando il comando di build se i sorgenti non sono puliti. Nessun finding — nessun cancello — nessun ciclo sprecato.

---

Il Principio

Il Sentinel Gate applica un invariante semplice:

zenzic check all [PATH] --strict  →  successo  →  il tuo strumento di build
                                  →  fallimento →  build bloccata

Il cancello scatta in locale — prima che tu faccia push, prima che la CI veda il branch. È la stessa analisi che viene eseguita nel tuo workflow di GitHub Actions, applicata nel momento in cui correggerla è meno costoso.

---

Ricettario per Ecosistema

Scegli la ricetta che corrisponde al tuo toolchain di build.

Docusaurus (npm scripts)

I progetti Docusaurus usano npm run build. Proteggi il comando in package.json:

package.json

{
  "scripts": {
    "zenzic": "uvx zenzic check all . --strict",
    "build": "npm run zenzic && docusaurus build"
  }
}

npm run build esegue ora Zenzic per primo. Se viene rilevato qualsiasi finding, docusaurus build non viene mai avviato. Il tuo comando CI esistente (npm run build) acquisisce il cancello automaticamente — non sono necessarie modifiche al YAML del workflow.

Versione fissata in produzione

Sostituisci uvx zenzic con uvx "zenzic==0.7.0" per una CI deterministica. Al primo install a caldo, uv memorizza nella cache la wheel — le esecuzioni successive sono quasi istantanee.

MkDocs (justfile / Makefile)

I progetti MkDocs usano tipicamente mkdocs build o un justfile. Proteggi la ricetta di build:

justfile

# Sentinel Gate — Zenzic deve passare prima che MkDocs compili
build:
    uv run zenzic check all . --strict
    mkdocs build --strict

O se preferisci una ricetta shell senza uv:

justfile

build:
    uvx zenzic check all . --strict
    mkdocs build --strict

Per chi usa Makefile:

Makefile

build:
	uvx zenzic check all . --strict
	mkdocs build --strict

Entrambi i comandi nella ricetta vengono eseguiti sequenzialmente. Un'uscita non-zero da zenzic check all interrompe la ricetta prima che mkdocs build venga raggiunto.

Zensical (shell / justfile)

I progetti Zensical possono proteggere la build con una semplice concatenazione di comandi:

build.sh

#!/usr/bin/env bash
set -euo pipefail

uvx zenzic check all . --strict
zensical build

Oppure tramite una ricetta justfile:

justfile

# Sentinel Gate — la documentazione deve essere pulita prima che Zensical la renderizzi
build:
    uvx zenzic check all . --strict
    zensical build

set -euo pipefail nello script shell garantisce che un'uscita non-zero da zenzic check all si propaghi immediatamente — zensical build non viene mai raggiunto.

Standalone (qualsiasi strumento)

Per i progetti senza motore di build — generatori di siti statici, documentazione distribuita come Markdown, o pipeline personalizzate — il pattern è sempre lo stesso:

uvx zenzic check all . --strict && il_tuo_comando_di_build

L'operatore && fa cortocircuito: se Zenzic esce con codice non-zero, il_tuo_comando_di_build non viene mai eseguito. Combina con qualsiasi Makefile, justfile, script package.json o punto di ingresso shell.

---

Perché il Gate in Locale e Non Solo in CI

Punto di scoperta	Costo per correggere
Prima della build (gate locale)	Secondi — l'editor è ancora aperto
Pipeline CI	Minuti — push, attesa, lettura log, correzione, re-push
Deploy in produzione	Ore — rollback, triage, hotfix

Il Sentinel Gate sposta la scoperta nel momento meno costoso possibile. Quando la CI viene eseguita, la documentazione è già pulita — la CI diventa una conferma piuttosto che un rilevatore.

---

Riferimento Codici di Uscita

Codice	Significato	Comportamento del Gate
0	Tutti i controlli superati	Build procede
1	Finding di qualità (link, orfani, placeholder)	Build bloccata per default; aggiungi --no-fail-under per permetterlo
2	Violazione Shield — credenziale rilevata	Sempre bloccata. Non sopprimibile.
3	Blood Sentinel — path traversal di sistema	Sempre bloccata. Non sopprimibile.

I codici di uscita 2 e 3 sono stop incondizionati. Nessun flag o configurazione può sopprimere un incidente di sicurezza.

---

Ambienti Pre-Lancio e di Staging

I link esterni a siti non ancora pubblici — domini di documentazione, tag di release GitHub, URL di staging — restituiscono HTTP 404 finché il deploy non è completato. Il Sentinel Gate blocca la build su questi, e il comportamento è corretto: un link esterno rotto è un finding reale.

Quando stai deliberatamente compilando la documentazione prima che il sito di destinazione vada live, istruisci il gate a saltare i controlli esterni per quella esecuzione usando ZENZIC_EXTRA_ARGS:

# Salta tutti i controlli sui link esterni — ambienti pre-lancio o senza rete
ZENZIC_EXTRA_ARGS="--no-external" just build

# Escludi solo un dominio pre-lancio specifico, mantieni tutti gli altri controlli esterni
ZENZIC_EXTRA_ARGS="--exclude-url https://zenzic.dev/" just build

ZENZIC_EXTRA_ARGS è una variabile d'ambiente letta sia da just sentinel che da just build. Inietta flag nell'invocazione di Zenzic senza modificare zenzic.toml o il justfile — la fonte di verità per la configurazione rimane invariata. Non impostata, si espande a vuota e il gate si comporta con piena severità.

Eccezione esplicita, non un nuovo default

ZENZIC_EXTRA_ARGS deve essere impostata esplicitamente ad ogni invocazione. Non viene persistita in nessun file di configurazione. Esegui just build senza la variabile per confermare che il gate blocchi ancora sui link rotti:

just build
# ✘ [EXTERNAL_LINK] blog/example.mdx:12: 'https://zenzic.dev/blog/' returned HTTP 404
# FAILED: Hard errors detected. Exit code 1 is mandatory.

La protezione è attiva per default. La variabile è un'eccezione dell'operatore, non una modifica alla configurazione.

✘docs/guides/setup.md:14Z101Broken link → 'install.md' (target not found)

✘docs/guides/old-api.mdZ402Orphan page — not reachable from any navigation

⚠docs/reference/config.md:3Z501Placeholder: "TODO: describe this parameter"

✘ 2 errors⚠ 1 warningScore: 67 / 100

Il finding sopra è ciò che appare con un link esterno pre-lancio. È accurato — l'URL non si risolve. ZENZIC_EXTRA_ARGS="--no-external" lo sopprime per una singola invocazione di build.

---

Correlati

• Integrazione CI/CD — workflow GitHub Actions che applicano lo

  stesso cancello nella tua pipeline

• Metriche di Salute — come Zenzic calcola il

  punteggio di qualità che il Sentinel Gate difende

• Riferimento Codici di Uscita — semantica completa

  dei codici di uscita