Tutte le modifiche rilevanti a Zenzic sono documentate qui. Il formato segue Keep a Changelog. Le versioni seguono il Semantic Versioning.
- Standalone Engine sostituisce Vanilla (Direttiva 037).
VanillaAdaptere la keywordengine = "vanilla"sono stati rimossi. Tutti i progetti devono migrare aengine = "standalone". Qualsiasizenzic.tomlche usa ancoraengine = "vanilla"genera unaConfigurationError [Z000]all'avvio con un messaggio di migrazione chiaro. Migrazione: sostituireengine = "vanilla"conengine = "standalone"nel propriozenzic.tomlo nel blocco[tool.zenzic].
-
Codici Finding (Zxxx) (Direttiva 036). Ogni diagnostica emessa da Zenzic ora porta un identificatore univoco leggibile dalla macchina (es.
Z101 LINK_BROKEN,Z201 SHIELD_SECRET,Z401 MISSING_DIRECTORY_INDEX). Il registro completo si trova insrc/zenzic/core/codes.py— unica fonte di verità per tutti i codici. -
Menu interattivo del Lab.
zenzic labsenza argomenti mostra ora l'indice degli atti per scegliere quale scenario esplorare. Eseguirezenzic lab <N>per avviare un atto specifico (0–8). L'opzione--actè stata sostituita da un argomento posizionale. -
Identità Standalone Mode.
StandaloneAdapterè il motore no-op canonico per progetti Markdown puri.zenzic initora scriveengine = "standalone"quando non viene rilevata nessuna configurazione di framework. -
Flag
--offlineper la risoluzione URL Flat. Disponibile sucheck all,check linksecheck orphans. Forza tutti gli adapter a produrre URL.html(es.guida/install.md→/guida/install.html) invece di slug in stile directory. -
Supporto multi-versione Docusaurus v3.
DocusaurusAdapterora identificaversions.json,versioned_docs/e le traduzioni versionate. -
Proxy Trasparente Zensical. Se viene dichiarato
engine = "zensical"mazensical.tomlè assente, l'adapter crea automaticamente un ponte con il tuomkdocs.ymlesistente. -
Ghost Routing consapevole delle versioni. I percorsi della documentazione versionata sono automaticamente classificati come
REACHABLE. -
Risoluzione Alias @site/. Aggiunto il supporto per l'alias di percorso
@site/inDocusaurusAdapter, permettendo la corretta risoluzione dei link relativi al progetto. -
Integrità dell'Indice di Directory. Nuovo metodo
provides_index(path)nel protocolloBaseAdapterper il rilevamento engine-aware delle directory prive di landing page. Il findingMISSING_DIRECTORY_INDEX(severità:info), emesso dazenzic check all, avvisa di ogni sottodirectory che contiene sorgenti Markdown ma nessun indice fornito dall'engine — prevenendo i 404 gerarchici prima del deploy. -
Notifiche nel Banner Sentinel. Nuovi messaggi di stato per l'attivazione della Modalità Offline e della Modalità Proxy.
-
Audit dei Guardiani: Allineamento Specifiche Ufficiali.
- Versioning Docusaurus: Corretta la mappatura URL della versione "latest" (prima voce
in
versions.json) per escludere il prefisso dell'etichetta di versione, allineandosi al comportamento ufficiale di Docusaurus. In precedenza ogni file versionato riceveva un prefisso/versione/, generando falsi positivi per tutte le pagine della versione latest. - Slug Docusaurus: Gli slug frontmatter assoluti (es.
slug: /mio-percorso) sono ora correttamente preceduti dallarouteBasePath(es./docs/mio-percorso/), allineandosi alla specifica DocusaurusnormalizeUrl([versionMetadata.path, docSlug]). - Collasso Intelligente dei File: La logica
isCategoryIndexora rispecchia esattamente Docusaurus:README.md,INDEX.md(case-insensitive) e{NomeCartella}/{NomeCartella}.mdcollassano nell'URL della directory genitore, prevenendo falsi positivi per le convenzioni valide di landing page di categoria. - Risoluzione Alias
@site/:InMemoryPathResolverora risolve i link@site/rispetto al corretto confinerepo_rootinvece di sfuggire tramite../, eliminando erroriPathTraversalspuri per tutti i link relativi al progetto Docusaurus.
- Versioning Docusaurus: Corretta la mappatura URL della versione "latest" (prima voce
in
-
Integrità dei Metadati. Corretto l'allineamento delle stringhe di versione in
CITATION.cffepyproject.toml. -
Default routeBasePath Docusaurus. Ripristinato
docscome prefisso URL predefinito per i progetti Docusaurus per corrispondere al comportamento ufficiale dell'engine. -
Parità Documentale Bilingue. Copertura completa della documentazione EN/IT per tutte le feature della v0.6.1 nelle guide Architettura, Motori e Comandi.
- Shield: bypass tramite caratteri Unicode di formato (ZRT-006). Caratteri Unicode invisibili (ZWJ U+200D, ZWNJ U+200C, ZWSP U+200B) inseriti all'interno di un token potevano eludere il pattern matching. Il normalizzatore ora rimuove tutti i caratteri Unicode di categoria Cf prima della scansione.
- Shield: bypass tramite offuscamento con entità HTML (ZRT-006). I riferimenti
a caratteri HTML (
AK→AK) potevano nascondere i prefissi delle credenziali. Il normalizzatore ora decodifica le entità&#NNN;/&#xHH;tramitehtml.unescape(). - Shield: bypass tramite interleaving di commenti (ZRT-007). Commenti HTML
(
<!-- -->) e commenti MDX ({/* */}) inseriti all'interno di un token potevano interrompere il pattern matching. Il normalizzatore ora rimuove entrambe le forme di commento. - Shield: rilevamento token spezzati tra righe (ZRT-007). Aggiunto un buffer
lookback di 1 riga tramite
scan_lines_with_lookback()per rilevare segreti suddivisi su due righe consecutive (es. scalari YAML folded). I duplicati sono soppressi tramite il set di tipi già rilevati sulla riga precedente.
--format jsonsui comandi di controllo singoli.check links,check orphans,check snippets,check referencesecheck assetsaccettano ora--format jsoncon uno schema uniformefindings/summary. I codici di uscita sono preservati in modalità JSON. (#55 — contributo di @xyaz1313)- Shield: rilevamento GitLab Personal Access Token. Lo scanner di credenziali
rileva ora i token
glpat-(9 famiglie di credenziali in totale). (#57 — contributo di @gtanb4l)
- Asimmetria exit-code JSON in
check orphansecheck assets. Entrambi i comandi ora distinguono la severitàerrordawarningprima di decidere il codice di uscita, in modo coerente concheck referencesecheck snippets. In precedenza, qualsiasi finding (inclusi i warning) attivava Exit 1 in modalità JSON.
- Rimosso il comando
zenzic serve. Zenzic è ora 100% privo di sotto-processi, concentrandosi esclusivamente sull'analisi statica del sorgente. Per visualizzare la documentazione, usa il comando nativo del tuo engine:mkdocs serve,docusaurus start, ozensical serve. Questa rimozione elimina l'unica eccezione al Pillar 2 (Nessun Sottoprocesso) e completa la purezza architetturale del framework. - Plugin MkDocs spostato in
zenzic.integrations.mkdocs— In precedenza inzenzic.plugin. Aggiornaremkdocs.ymle reinstallare il pacchetto; il plugin viene ora auto-scoperto tramite l'entry pointmkdocs.plugins. Richiedepip install "zenzic[mkdocs]".
- Layered Exclusion Manager — Nuova gerarchia di esclusione a 4 livelli
(Guardrail di Sistema > Inclusioni Forzate + VCS > Config > CLI). Parser
gitignore pure-Python (
VCSIgnoreParser) con pattern regex pre-compilati. Nuovi campi di configurazione:respect_vcs_ignore,included_dirs,included_file_patterns. - Discovery Universale — Zero chiamate
rglobnel codebase. Tutta l'iterazione sui file passa attraversowalk_files/iter_markdown_sourcesdadiscovery.py. Parametroexclusion_managerobbligatorio su tutti i punti d'ingresso di scanner e validator — nessun Optional, nessun fallback. - Flag CLI di Esclusione —
--exclude-dire--include-dirripetibili su tutti i comandi check,scoreediff. - Cache Adapter — Cache a livello di modulo con chiave
(engine, docs_root, repo_root). Singola istanziazione dell'adapter per sessione CLI. - F4-1 Protezione Jailbreak —
_validate_docs_root()rifiuta percorsidocs_dirche escono dalla radice del repository (Sentinella di Sangue Exit 3). - F2-1 Hardening Shield — Le righe che superano 1 MiB vengono troncate silenziosamente prima del matching regex per prevenire ReDoS.
- Namespace
zenzic.integrations— Plugin MkDocs spostato dazenzic.pluginazenzic.integrations.mkdocs. Registrato come entry point ufficialemkdocs.plugins. Il core è ora privo di import specifici per engine. Installa l'extra:pip install "zenzic[mkdocs]".
- BREAKING (Alpha): il parametro
exclusion_managerè ora obbligatorio suwalk_files,iter_markdown_sources,generate_virtual_site_map,check_nav_contract, e tutte le funzioni dello scanner. Nessun defaultNoneretrocompatibile.
- Supporto Glob Pattern per
excluded_assets— Le voci diexcluded_assetssono ora interpretate tramitefnmatch(sintassi glob:*,?,[],**). I percorsi letterali continuano a funzionare come prima. Questo allineaexcluded_assetsconexcluded_build_artifactseexcluded_file_patterns, dando all'intera API di esclusione un linguaggio unico e coerente. base_urlin[build_context]— Nuovo campo opzionale che permette di dichiarare esplicitamente la base URL del sito. Quando impostato, l'adapter Docusaurus salta l'estrazione statica dadocusaurus.config.ts, eliminando il warning di fallback "dynamic patterns" per le configurazioni che usanoasync,import()orequire().- Routing Guidato dai Metadati — Nuovo dataclass
RouteMetadatae metodoget_route_info()nel protocolloBaseAdapter. Tutti e quattro gli adapter (Vanilla, MkDocs, Docusaurus, Zensical) implementano la nuova API.build_vsm()preferisce il percorso metadata-driven quando disponibile, con fallback alla coppia legacymap_url()+classify_route()per gli adapter di terze parti. - Estrazione Centralizzata del Frontmatter — Utility engine-agnostiche in
_utils.py:extract_frontmatter_slug(),extract_frontmatter_draft(),extract_frontmatter_unlisted(),extract_frontmatter_tags(), ebuild_metadata_cache()per il harvesting eager single-pass del frontmatter YAML su tutti i file Markdown. - Dataclass
FileMetadata— Rappresentazione strutturata del frontmatter per file:slug,draft,unlisted,tags. - Shield IO Middleware —
safe_read_line()scansiona ogni riga del frontmatter attraverso lo Shield prima che qualsiasi parser la veda. L'eccezioneShieldViolationfornisce un errore strutturato con payloadSecurityFinding. - Test di Conformità del Protocollo — 43 nuovi test in
test_protocol_evolution.py: validazioneruntime_checkabledel protocollo, invariantiRouteMetadata, test di contrattoget_route_info()per tutti gli adapter, stress test Hypothesis con percorsi estremi, sicurezza pickle, estrazione frontmatter, middleware Shield, e operazione senza warning di VanillaAdapter.
- BREAKING:
excluded_assetsusa fnmatch — Tutte le voci sono ora interpretate come pattern glob. I percorsi letterali continuano a funzionare (sono pattern validi), ma pattern come**/_category_.jsonoassets/brand/*sono ora supportati nativamente. L'implementazione precedente basata sulla sottrazione di insiemi è stata rimossa.
- Warning "dynamic patterns" di Docusaurus emesso due volte — Quando
base_urlè dichiarato inzenzic.toml, l'adapter non chiama più_extract_base_url(), sopprimendo completamente il warning duplicato.
Alpha 1 della serie v0.6. Zenzic evolve da un linter MkDocs-aware a un Analizzatore di Piattaforme Documentali. Questo rilascio introduce l'adapter per il motore Docusaurus v3 — il primo adapter non-MkDocs/Zensical — e segna l'inizio della strategia di migrazione Obsidian Bridge.
- Adapter Docusaurus v3 (Full Spec): Nuovo adapter engine-agnostico con
parsing statico AST-like per
docusaurus.config.ts/js. Adapter puro Python conforme al protocolloBaseAdapter. Gestisce file sorgente.mde.mdx, modalità sidebar auto-generata (tutti i fileREACHABLE), geografia i18n Docusaurus (i18n/{locale}/docusaurus-plugin-content-docs/current/), rilevamento Ghost Route per le pagine indice delle locale, ed esclusione di file/directory con prefisso_(IGNORED). Registrato come adapter built-in con entry-pointdocusaurus = "zenzic.core.adapters:DocusaurusAdapter".- Estrazione
baseUrl: Parser statico multi-pattern che supportaexport default,module.exportse pattern di assegnazioneconst/let. I commenti JS/TS vengono rimossi prima dell'estrazione. Nessun sottoprocesso Node.js (conformità Pilastro 2). - Estrazione
routeBasePath: Rilevamento automatico dirouteBasePathdai preset e blocchi plugin Docusaurus (es.@docusaurus/preset-classic). Supporta stringa vuota (docs alla radice del sito). - Supporto Slug: Gli override
slug:nel frontmatter Markdown sono ora correttamente mappati nella VSM. Gli slug assoluti (/custom-path) sostituiscono l'URL completo; gli slug relativi sostituiscono l'ultimo segmento del percorso. - Rilevamento Config Dinamica: Rilevamento intelligente di config
creator asincroni, chiamate
import()/require()e export basati su funzione. Fallback abaseUrl='/'con warning utente — mai crash, mai assunzioni.
- Estrazione
- Hook factory
from_repo()perDocusaurusAdapter: Scopre automaticamentedocusaurus.config.tso.jse costruisce l'adapter con ilbaseUrlerouteBasePathcorretti. - Topologia i18n Migliorata: Mappatura nativa per la struttura delle
directory
i18n/di Docusaurus e risoluzione delle rotte specifiche per locale.
tests/test_docusaurus_adapter.py— 65 test in 12 classi di test. Copertura completa del refactor dell'adapter Docusaurus: parsing config (CFG-01..07), estrazionerouteBasePath(RBP-01), supporto slug frontmatter (SLUG-01), rilevamento config dinamica, rimozione commenti, integrazionefrom_repo(), regressione URL mapping e classificazione rotte.
Rilascio Alpha 5. Revisione del linguaggio visivo: Guida di Stile Sentinel, refactoring delle griglie a schede, normalizzazione di admonition e icone, 102 anchor ID strategici, effetti hover CSS per le schede, e pipeline di generazione screenshot completamente automatizzata. Rimosso template PDF legacy. Tracking changelog stabilizzato. Test E2E CLI di sicurezza aggiunti; bug
--exit-zerocorretto (exit 2/3 ora incondizionatamente non sopprimibili, conforme al contratto documentato).
-
Guida di Stile Sentinel — riferimento canonico del linguaggio visivo (
docs/internal/style-guide-sentinel.md+ specchio italiano) che definisce griglie a schede, tipi di admonition, vocabolario icone e convenzioni anchor-ID. -
Generazione screenshot automatizzata — SVG Blood & Circular.
scripts/generate_docs_assets.pyora genera tutti e cinque gli screenshot della documentazione. Gli SVG Blood Sentinel e Circular Link erano asset statici realizzati a mano; ora sono generati deterministicamente da fixture sandbox dedicate. -
Tracking bumpversion CHANGELOG.it.md. Il changelog italiano aggiunto a
[tool.bumpversion.files]inpyproject.toml, garantendo la sincronizzazione delle intestazioni di versione durante le esecuzioni dibump-my-version.
--exit-zeronon sopprime più gli exit di sicurezza incheck all. Gli exit code 2 (Shield breach) e 3 (Blood Sentinel) erano protetti danot effective_exit_zeroincheck all, in contraddizione con il contratto documentato. Le guardie sono state rimosse — exit 2 e 3 sono ora incondizionali.
tests/test_cli_e2e.py— 8 test E2E CLI di sicurezza. Test full-pipeline (nessun mock) che verificano il contratto exit-code: Blood Sentinel (Exit 3), Shield Breach (Exit 2),--exit-zeronon sopprime exit di sicurezza, priorità Exit 3 > Exit 2. Chiude gap:docs/internal/arch_gaps.md§ "Security Pipeline Coverage".
-
Refactoring Griglie a Schede. Pagine documentazione standardizzate con sintassi griglia Material for MkDocs.
-
Normalizzazione Admonition. Stili callout ad-hoc sostituiti con tipi canonici (
tip,warning,info,example). -
Normalizzazione Icone. Icone non-Material rimosse; standardizzate al set
:material-*:. -
102 Anchor ID Strategici posizionati in 70 file di documentazione per deep-linking stabile.
-
Override CSS Schede. Effetti hover e stile schede coerente via
docs/assets/stylesheets/.
docs/assets/pdf_cover.html.j2— template Jinja2 copertina PDF legacy. Artefatto orfano senza riferimenti nella pipeline di build; rimosso per ridurre la superficie di manutenzione.
Rilascio Alpha 4. Quattro vulnerabilità confermate chiuse (ZRT-001–004), tre nuovi pilastri di hardening aggiunti (Sentinella di Sangue, Integrità del Grafo, Scudo Esadecimale), e piena parità documentale bilingue raggiunta. In attesa di revisione manuale prima della promozione a Release Candidate.
Branch:
fix/sentinel-hardening-v0.5.0a4
-
Integrità del grafo — rilevamento link circolari. Zenzic ora pre-calcola un registro dei cicli (Fase 1.5) tramite ricerca depth-first iterativa (Θ(V+E)) sul grafo dei link interni risolti. Ogni link il cui target appartiene a un ciclo emette un finding
CIRCULAR_LINKcon severitàinfo. I link di navigazione reciproca (A ↔ B) sono una struttura valida della documentazione; il finding è puramente informativo — non influisce mai sugli exit code in modalità normale o--strict. O(1) per query in Phase 2. Le Ghost Route (URL canonici generati da plugin senza file sorgente fisico) sono correttamente escluse dal grafo dei cicli. -
INTERNAL_GLOSSARY.toml— registro bilingue EN↔IT dei termini tecnici (15 voci) per un vocabolario coerente tra documentazione inglese e italiana. Copre i concetti principali: Porto Sicuro, Rotta Fantasma, Mappa del Sito Virtuale, Motore a Due Passaggi, Scudo, Sentinella di Sangue e altri. Mantenuto da S-0. Tutti i termini constable = truerichiedono un ADR prima della rinomina. -
Parità documentale bilingue.
docs/checks.mdedocs/it/checks.mdaggiornati con le sezioni Sentinella di Sangue, Link Circolari e Scudo Esadecimale.CHANGELOG.it.mdcreato. Piena parità EN↔IT applicata per il Protocollo di Parità Bilingue.
-
Sentinella di Sangue — classificazione degli attraversamenti di percorso (Exit Code 3).
check linksecheck allora classificano i finding di path-traversal per intenzione. Un href che esce dadocs/e si risolve in una directory di sistema del SO (/etc/,/root/,/var/,/proc/,/sys/,/usr/) viene classificato comePATH_TRAVERSAL_SUSPICIOUScon severitàsecurity_incidente attiva l'Exit Code 3 — un nuovo exit code dedicato riservato alle sonde del sistema host. L'Exit 3 ha priorità sull'Exit 2 (violazione credenziali) e non viene mai soppresso da--exit-zero. Gli attraversamenti fuori confine ordinari (es.../../repo-adiacente/) restanoPATH_TRAVERSALcon severitàerror(Exit Code 1). -
Scudo Esadecimale — rilevamento di payload hex-encoded. Un nuovo pattern built-in dello Shield,
hex-encoded-payload, rileva sequenze di tre o più escape hex\xNNconsecutive ((?:\\x[0-9a-fA-F]{2}){3,}). La soglia{3,}evita falsi positivi sulle singole escape hex comuni nella documentazione delle regex. I finding escono con codice 2 (Shield, non sopprimibile) e si applicano a tutti i flussi di contenuto inclusi i blocchi di codice delimitati. -
[ZRT-001] Shield Blind Spot — Bypass YAML Frontmatter (CRITICO).
_skip_frontmatter()veniva usato come sorgente di righe dello Shield, scartando silenziosamente ogni riga nel blocco YAML---del file prima che il motore regex girasse. Qualsiasi coppia chiave-valore (aws_key: AKIA…,github_token: ghp_…) era invisibile allo Shield. Fix: Il flusso Shield ora usaenumerate(fh, start=1)grezzo — ogni byte del file viene scansionato. Il flusso contenuto usa ancora_iter_content_lines()con salto del frontmatter per evitare falsi positivi da valori di metadati. Architettura Dual-Stream. -
[ZRT-002] ReDoS + Deadlock ProcessPoolExecutor (ALTO). Un pattern
[[custom_rules]]come^(a+)+$superava il controllo_assert_pickleable()e veniva distribuito ai worker process senza timeout. Due difese aggiunte: — Canary (prevenzione):_assert_regex_canary()stress-testa ogni patternCustomRulesotto un watchdogsignal.SIGALRMdi 100 ms. I pattern ReDoS sollevanoPluginContractErrorprima della prima scansione. — Timeout (contenimento):ProcessPoolExecutor.map()sostituito consubmit()+future.result(timeout=30). -
[ZRT-003] Bypass Shield Split-Token — Offuscamento Tabelle Markdown (MEDIO). Il separatore
|delle tabelle Markdown spezzava i token segreti su più celle. Fix: Le righe di tabella vengono de-pipe prima della scansione Shield. -
[ZRT-004] Injection Path Traversal nei Link Reference (BASSO). Link reference con href malevoli potevano sfuggire alla sandbox
docs/. Fix: La validazione PATH_TRAVERSAL applicata ai link reference come ai link inline.
- Pipeline CI/CD corretta per Node.js 24.
cloudflare/wrangler-action@v3invocanpx wranglersenza il flag--yes; npm 10+ sui runner GitHub con Node.js 24 blocca i prompt non interattivi, causando il fallimento del deploy su Cloudflare Pages. Fix: pre-installazione globale diwrangler@latestprima dell'esecuzione dell'action, così npx trova il binario nel PATH senza scaricarlo.FORCE_JAVASCRIPT_ACTIONS_TO_NODE24=truesilenzia il warning di deprecazione di Node.js 20 prima della migrazione forzata di giugno 2026. Tracciato inarch_gaps.md. Branch:fix/v050a4-infra-alignment.
Branch:
feat/sentinel-v0.5.0a3
- Sistema Plugin —
[[custom_rules]]inzenzic.tomlper regole regex personalizzate.PluginContractErrorper la validazione contratto a boot. - Regex Canary — watchdog SIGALRM 100 ms per backtracking catastrofico.
- Hooks Pre-commit — configurazione ufficiale per pipeline CI.
- UI Sentinel — palette colori, reporter a griglia, output Sentinel rinnovato.
Branch:
feat/sentinel-v0.5.0a1
- AdaptiveRuleEngine — motore di analisi estensibile con Phase 3.
- Hybrid Adaptive Engine — integrazione MkDocs + motore adattivo.
- Pannelli Sentinel — output strutturato per tutti i controlli.
Branch:
feat/engine-decoupling
- Factory entry-point dinamica —
--engineCLI flag; protocollohas_engine_config. - InMemoryPathResolver — resolver agnostico rispetto al motore.
- Tower of Babel Guard — fallback i18n per ancora mancante nella locale.
- Two-Pass Engine — Phase 1 (I/O parallelo) + Phase 2 (validazione O(1)).
- Virtual Site Map (VSM) — proiezione logica del sito renderizzato.
- Shield — rilevamento segreti, Stream Dual, exit code 2.
- Validazione anchor cross-lingua — Tower of Babel Guard.