Passa al contenuto principale

Architettura dell'Adattatore Docusaurus

Il DocusaurusAdapter è responsabile della traduzione dello stato del filesystem fisico di un progetto Docusaurus nel Virtual Site Map (VSM) universale di Zenzic. Poiché Docusaurus è un framework React basato su Node.js, Zenzic deve emularne la logica di routing interamente in Python tramite analisi statica.

Il Contratto di Emulazione​

Zenzic non esegue docusaurus build né valuta JavaScript. Al contrario, analizza staticamente docusaurus.config.ts (o .js) per estrarre le configurazioni dei plugin. Questo permette a Zenzic di prevedere accuratamente gli URL finali generati dalla pipeline di build di Docusaurus.

Semantica di Risoluzione delle Route​

Docusaurus genera route in base a una combinazione di path del filesystem e configurazione dei plugin. Zenzic emula questo comportamento utilizzando le seguenti regole:

  1. Override Frontmatter (slug): Docusaurus consente agli autori di sovrascrivere la route predefinita basata sul filesystem utilizzando il campo frontmatter slug. Zenzic rispetta questa regola:

    • Slug Assoluti: Se uno slug inizia con un / (es. slug: /custom), Docusaurus antepone il routeBasePath del plugin. Zenzic antepone correttamente il routeBasePath agli slug assoluti per prevenire falsi positivi di pagine orfane.
    • Slug Relativi: Se uno slug è relativo (es. slug: custom), sostituisce l'ultimo segmento del path del filesystem.

  2. Estrazione della Data del Blog: I post del blog di Docusaurus spesso usano una convenzione per i nomi dei file come YYYY-MM-DD-slug.md. Quando genera l'URL, Docusaurus estrae la data nei segmenti del path (/YYYY/MM/DD/slug/). Zenzic analizza nativamente questi nomi di file usando espressioni regolari per emulare l'esatta logica di generazione degli URL, assicurando che i post del blog con date siano mappati correttamente nel VSM.

  3. Linking Basato su File: I link che utilizzano percorsi assoluti e fanno riferimento al filesystem sorgente (es. /docs/guide/install.md) vengono risolti da Zenzic esattamente come li risolve Docusaurus, mappandoli sui rispettivi URL canonici nel VSM.

Questo approccio architetturale permette a Zenzic di fornire una validazione dei link senza falsi positivi e rilevamento degli orfani senza il sovraccarico di un runtime Node.js o l'esecuzione dinamica.

Limitazioni Note e Mitigazioni​

Zenzic impone un determinismo assoluto attraverso un'architettura di analisi statica in puro Python. Di conseguenza, non esegue JavaScript o TypeScript. Questo impone due rigidi confini fisici nell'emulazione della semantica di routing di Docusaurus:

Alias @site di Webpack​

Zenzic non può risolvere gli alias di Webpack dinamicamente. I link che utilizzano l'alias @site/ si basano sulla risoluzione dei moduli di Node.js durante la fase di build di Webpack. Poiché questo processo è dinamico, l'analisi statica non può intercettarlo in modo affidabile, e questi link produrranno errori Z104 (Missing Internal Route).

Indici di Categoria Generati​

Le sidebar di Docusaurus generano dinamicamente percorsi virtuali /category/ a runtime tramite sidebars.js o sidebars.ts. Poiché Zenzic non può eseguire TypeScript per scoprire queste rotte virtuali, i link che puntano agli indici di categoria generati produrranno errori Z101 (Orphaned File) o Z104 (Missing Internal Route).

Mitigazione Ufficiale​

Per silenziare questi falsi positivi architetturali senza subire penalità sul DQS, devi implementare policy di directory esplicite nel tuo .zenzic.toml (o .zenzic.local.toml). Dovresti prendere di mira solo le directory specifiche in cui si verificano questi confini architetturali per evitare di mascherare problemi legittimi nella tua documentazione principale. Non alterare i tuoi link Docusaurus validi.

[governance.directory_policies]
# Mitigazione chirurgica per specifici file/cartelle contenenti indici generati o alias @site
"website/docs/guides/docs/sidebar/**" = ["Z101", "Z104"]
"website/docs/migration/**" = ["Z104"]

Nota Strategica: Questa limitazione è temporanea. Nella versione v0.12.0, Zenzic implementerà la Bridge Architecture. Introducendo docusaurus-plugin-zenzic, il motore Python acquisirà un dump fisico .zenzic-vsm.json accurato al 100% direttamente dal ciclo di vita di Docusaurus, eliminando completamente i vincoli euristici.