Passa al contenuto principale

La Trinità di Zenzic: Codice, Documentazione e Action

Zenzic è molto più di un linter. È un Sistema di Conoscenza Sovrano — un ecosistema in cui logica, intenzione ed esecuzione sono permanentemente sincronizzati. Per garantire un vero Exclusion Zone, Zenzic è organizzato in una Trinità dell'Integrità: tre repository che formano un ciclo di feedback chiuso, dove ciascuno rafforza gli altri.

1. Il Core — Il Corpo​

Il repository zenzic è il livello di esecuzione tattica. Contiene ogni riga di logica di analisi che applica i Tre Pilastri.

ComponenteRuolo
Virtual Site Map (VSM)Costruisce una proiezione in memoria del sito finale dai soli file sorgente. Nessuna build richiesta.
Credential ScannerScansiona ogni riga del sorgente grezzo alla ricerca di pattern di credenziali prima di qualsiasi altro passaggio.
Adapter ProtocolTraduce la configurazione specifica del motore (Docusaurus, MkDocs, Zensical, Standalone) in un modello di analisi unificato.
Layered Exclusion ManagerUnifica guardrail di sistema, inclusioni forzate, override CLI, ignore VCS e configurazione utente in un’unica gerarchia di passaggi deterministica per garantire un perimetro di scansione pulito.

Il Core applica la legge. Non la decide.

  1. Velocità & Shift-Left: Le build SSG (basate su Node.js, Go o Python) richiedono la compilazione completa del sito e tipicamente girano in loop CI più lenti. Zenzic esegue analisi statica locale su testo sorgente e metadati prima della build, con feedback pre-commit in millisecondi.
  2. Sicurezza: I controlli nativi degli SSG non bloccano il commit di credenziali esposte o tentativi di path traversal. Zenzic applica finding di sicurezza nel tier Z2xx e blocca sugli exit di sicurezza.
  3. Governance: Gli SSG non applicano contratti di governance come obsolescenza brand (Z601), deriva di parità i18n (Z602) o asset orfani (Z405). Zenzic li espone come contratti espliciti e auditabili.
  4. Diagnostica azionabile: Quando falliscono rotte generate, l'output SSG è in genere un 404/fallimento build generico. Zenzic usa reverse mapping VSM per indicare il file sorgente esatto e il contesto frontmatter che generano la rotta virtuale in errore.

2. La Documentazione — L'Anima​

Il repository zenzic-doc è il Livello Costituzionale del progetto. Non è solo un manuale utente — è la fonte di verità che definisce perché il motore esiste e perché ogni regola è quella che è.

Il Framework Diátaxis​

Il contenuto è organizzato in quattro quadranti rigorosi: Tutorial (apprendimento), Guide pratiche (obiettivi specifici), Reference (dati esaustivi) ed Explanation (comprensione). Questo previene la deriva dei contenuti: ogni collaboratore sa sempre esattamente dove collocare una nuova informazione.

Architectural Decision Records (ADR)​

Ogni scelta tecnica importante è codificata in un ADR archiviato in developers/explanation/. Ogni record descrive il problema, la decisione, la motivazione e le conseguenze permanenti. Gli ADR sono la memoria istituzionale del progetto — la prova scritta che nessuna decisione è stata presa con leggerezza.

Il corpus degli ADR garantisce che la filosofia del Exclusion Zone rimanga stabile nel tempo, indipendentemente da chi contribuirà al progetto in futuro.

3. La Action — Il Braccio​

Il repository zenzic-action è il livello operativo. Traduce la logica del Core in un perimetro difensivo per le pipeline CI/CD reali.

.github/workflows/zenzic.yml

- uses: PythonWoods/zenzic-action@<version>

  with:
    version: "<version>"
    format: sarif
    upload-sarif: true
    fail-on-error: true

La Action espone il contratto dei codici di uscita del Core direttamente ai runner di GitHub Actions: i finding di qualità (uscita 1) sono configurabili; gli incidenti di sicurezza (uscita 2/3) non sono mai sopprimibili. Il gate CI è matematicamente identico al gate locale.

Il Ciclo di Feedback​

La Trinità non è una gerarchia — è un ciclo. Ogni repository informa e vincola gli altri:

  ┌────────────────────────────────────────────────┐
  │                                                │
  │   Il Core applica le regole definite dall'Anima│
  │          ↓                                     │
  │   L'Anima registra le decisioni prese durante  │
  │   l'implementazione del Core e la revisione    │
  │   della community                              │
  │          ↓                                     │
  │   Il Braccio porta il Core nel mondo reale,   │
  │   restituendo i fallimenti all'Anima come      │
  │   candidati a nuovi ADR                        │
  │          ↓                                     │
  │   L'Anima aggiorna gli invarianti del Core     │
  │          ↑__________________________________ │
  │                                                │
  └────────────────────────────────────────────────┘

Una modifica al Core che non si riflette nell'Anima è un ghost commit. Una Action che espone comportamenti non documentati nell'Anima è un contratto silenzioso. La Trinità è completa solo quando tutti e tre sono sincronizzati — garantito dalla Legge della Testimonianza Contemporanea.

Consapevolezza Architetturale​

Zenzic è progettato per la Memoria Istituzionale. Due proprietà rendono questo possibile:

Superficie Regole Deterministica — Lo Specchio Strutturale​

Il core zenzic espone una superficie regole deterministica tramite registro codici, catalogo finding e contratti adapter. Lo stato strutturale viene letto da registri espliciti e output CLI stabili (inspect capabilities, inspect codes, inspect routes), non inferito da euristiche runtime.

Corpus degli ADR — Lo Specchio delle Decisioni​

Ogni scelta architetturale vive in un file MDX strutturato con un formato canonico: sidebar_label, **Status:**, ## Context, ## Decision, ## Rationale. Questo rende la storia delle decisioni leggibile per le macchine per design.

Insieme, la superficie regole deterministica e il corpus degli ADR formano un livello di contesto trasparente:

  • Per gli esseri umani: un percorso chiaro e prevedibile dalla filosofia all'implementazione —

    senza dover fare archeologia nel codice.

  • Per i sistemi di automazione: un contesto strutturato e non ambiguo che mantiene i

    suggerimenti generati allineati agli invarianti fondamentali del progetto.

:::info Il Exclusion Zone è un Sistema di Conoscenza Sovrano Zenzic non è solo uno strumento che usi. È un ecosistema di cui puoi fidarti — perché le sue regole, le sue decisioni e la sua struttura sono sempre leggibili, sempre sincronizzate e sempre oneste. :::