Passa al contenuto principale

Design della Migrazione dei Motori

Per il playbook operativo step-by-step, vedi Migrazione dei Motori.

I file sorgente sopravvivono al motore di build​

I motori di build evolvono. Cambiano formati di configurazione, abbandonano sistemi di plugin, si fondono con piattaforme commerciali, o semplicemente smettono di essere mantenuti. Quando ciò accade, ciò che è a rischio non sono i file Markdown — quelli sono testo semplice e saranno sempre leggibili. Ciò che è a rischio è l'investimento in struttura: la navigazione, le convenzioni i18n, il link graph, l'organizzazione degli asset costruiti nel tempo.

Il ruolo di Zenzic in una migrazione non è rendere il passaggio più veloce. È rendere il passaggio provabilmente sicuro — garantendo che ogni invariante strutturale venga misurato prima, durante e dopo la migrazione, e che ogni regressione sia immediatamente visibile e attribuita con precisione.

Questa garanzia si basa su un singolo principio architetturale: Zenzic linta la sorgente, mai il build. Legge mkdocs.yml, zensical.toml e i file Markdown come dati semplici. Non importa né esegue mai un framework di build. Questo significa che:

  • Zenzic comprende la struttura della documentazione anche se il binario di build che la interpretava non funziona più.
  • Eseguire zenzic check all su un progetto nel mezzo di una migrazione produce la stessa analisi di un progetto pienamente operativo — perché i file sorgente non sono cambiati.
  • Cambiare engine in .zenzic.toml (una riga) è sufficiente per validare se il contenuto è strutturalmente compatibile con un nuovo motore, senza toccare un singolo file Markdown.

Questo è l'Exclusion Zone: un layer di validazione fisso che rimane valido prima, durante e dopo qualsiasi cambio di motore di build.

MkDocsAdapter: preservazione della struttura come dato​

MkDocsAdapter tratta mkdocs.yml come una struttura dati pura — un insieme di path di nav, dichiarazioni di plugin e impostazioni di locale. Estrae ciò di cui ha bisogno (albero di nav, configurazione i18n, flag di plugin come reconfigure_material) e consegna il risultato al Rule Engine come oggetti Python tipizzati. Non chiama mai mkdocs build, non importa mkdocs e non dipende da alcun plugin installato o funzionante.

La conseguenza pratica è che MkDocsAdapter preserva il contratto strutturale MkDocs 1.x come specifica statale versionata. Finché il mkdocs.yml descrive una struttura MkDocs 1.x valida, Zenzic la comprenderà e la validerà — indipendentemente da ciò che qualsiasi binario di build fa o non fa. Eseguire zenzic check all con engine = "mkdocs" testa il contenuto rispetto a quel contratto documentato, non rispetto a una specifica versione binaria.

Questo rende l'output di Zenzic un certificato di qualità portabile: se Zenzic dice che la documentazione è strutturalmente valida, quella affermazione è vera indipendentemente dal motore che verrà usato per renderizzarla domani.

Modello di resilienza MkDocs 2.0​

Se MkDocs 2.0 uscisse domani con breaking changes, un utente Zenzic manterrebbe un quality gate stabile per le sorgenti MkDocs 1.x esistenti.

Perché questo vale tecnicamente:

  • MkDocsAdapter analizza mkdocs.yml come dati statici e non importa MkDocs.
  • Zenzic non esegue mai il codice dei plugin; le sezioni plugin vengono lette come semplice config.
  • Tag YAML sconosciuti e chiavi future sono tollerati da un loader permissivo.

Risultato: la pipeline di validazione non dipende dal ciclo di vita di un singolo binario di build. Si può continuare a lintare le convenzioni MkDocs 1.x mentre si valutano percorsi di migrazione.

i18n: validare la struttura indipendentemente dal rendering​

Il plugin i18n di MkDocs (convenzioni folder-mode e suffix-mode) definisce una struttura di contenuto ben specificata: directory di locale, catene di fallback, nav shadowing per locale. Zenzic codifica questa specifica in MkDocsAdapter e nella Virtual Site Map indipendentemente da qualsiasi implementazione di rendering.

Questo è rilevante durante le transizioni di motore. Quando un motore di build sta ancora maturando il suo supporto i18n, esiste una finestra in cui le regole strutturali dell'impostazione i18n sono ben definite ma la capacità di rendering del motore potrebbe non essere ancora completa. Zenzic opera interamente nel dominio strutturale:

  • Risoluzione cross-locale dei link — un link da una pagina italiana a un asset solo-inglese viene risolto rispetto alla catena di fallback definita in mkdocs.yml, non rispetto all'output del build.
  • Rilevamento Ghost Route — i punti di ingresso locale generati in fase di build (es. /it/) sono marcati come REACHABLE nella VSM, quindi non vengono mai segnalati come orfani, anche se non sono mai stati renderizzati.
  • Soppressione directory locale — i file sotto docs/it/, docs/fr/, ecc. vengono classificati come shadow locale, non come orfani.

Si può quindi validare una struttura i18n complessa con Zenzic e avere la certezza della sua coerenza interna — il link graph è corretto, le catene di fallback sono intatte, la nav è completa — prima di impegnarsi con qualsiasi motore di rendering.