From 7bfa089310831b7ffb8036b337dbaf287efc4810 Mon Sep 17 00:00:00 2001 From: PythonWoods-Dev Date: Fri, 8 May 2026 09:06:24 +0200 Subject: [PATCH 01/18] =?UTF-8?q?docs:=20add=20[Unreleased]=20changelog=20?= =?UTF-8?q?entry=20(Branch=20Parity=20Rule=20=E2=80=94=20Core=20v0.7.1)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit No code changes (Node/Docusaurus ecosystem). Tracks alignment with Zenzic Core release/v0.7.1 infrastructure patch (Boundary Testing matrix fix, Mypy floor lowered to 3.10). --- CHANGELOG.it.md | 11 +++++++++++ CHANGELOG.md | 11 +++++++++++ 2 files changed, 22 insertions(+) diff --git a/CHANGELOG.it.md b/CHANGELOG.it.md index 329439b..3c48312 100644 --- a/CHANGELOG.it.md +++ b/CHANGELOG.it.md @@ -9,6 +9,17 @@ Le versioni seguono la linea di rilascio di Zenzic Core sotto la Branch Parity R --- +## [Non Rilasciato] + +#### Aggiunto + +- **Branch Parity Rule — parity snapshot con Core v0.7.1:** Nessuna modifica al codice + in questo repository (ecosistema Node/Docusaurus). Questa voce traccia l'allineamento + con la release di allineamento infrastrutturale di Zenzic Core (fix della matrice + Boundary Testing, floor Mypy abbassato a 3.10). + +--- + ## [0.7.0] — 2026-05-07 — Quartz Maturity (Stable) > **Fonte autorevole:** [zenzic.dev](https://zenzic.dev). Questo file è la diff --git a/CHANGELOG.md b/CHANGELOG.md index 331fcc4..83bc34e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,17 @@ Versions track the Zenzic Core release line under the Branch Parity Rule. --- +## [Unreleased] + +#### Added + +- **Branch Parity Rule — snapshot parity with Core v0.7.1:** No code changes in this + repository (Node/Docusaurus ecosystem). This entry tracks alignment with the Zenzic + Core infrastructure alignment release (Boundary Testing matrix fix, Mypy floor + lowered to 3.10). + +--- + ## [0.7.0] — 2026-05-07 — Quartz Maturity (Stable) > **Authoritative source:** [zenzic.dev](https://zenzic.dev). This file is the From 261d9c38651b5f8c2249524191e325e88c7b8735 Mon Sep 17 00:00:00 2001 From: PythonWoods-Dev Date: Fri, 8 May 2026 09:57:29 +0200 Subject: [PATCH 02/18] =?UTF-8?q?refactor(nox):=20remove=20preflight=20ses?= =?UTF-8?q?sion,=20rename=20verify-docs=E2=86=92verify-codes-parity,=20add?= =?UTF-8?q?=20Graceful=20Degradation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Remove nox preflight session (duplicated just verify; bare uvx zenzic without version pin) - Rename verify-docs → verify-codes-parity (nox session + function) - Step 1 rewritten: ZENZIC_PROJECT_PATH-aware Graceful Degradation - Core Maintainer: uv run --project (local source) - External Contributor: uv run --with zenzic (published PyPI fallback) - justfile: add verify-codes recipe; update verify target to 4-Gates (lint-all + typecheck + build + verify-codes) - docs sweep (EN + IT): all stale preflight/verify-docs references updated - README.md/README.it.md: command table + code block - CONTRIBUTING.md: pre-push gate section - docs/how-to/add-badges.mdx: nox -s preflight → nox -s build - developers/explanation/adr-bilingual-structural.mdx: just preflight → just lint-all - developers/how-to/sovereign-override-404-shield.mdx: checklist item - docs/how-to/configure-ci-cd.mdx: new Doc-Code Parity section (verify-codes-parity + Graceful Degradation table) - CHANGELOG.md + CHANGELOG.it.md: [Unreleased] ### Changed entry added --- CHANGELOG.it.md | 14 ++++ CHANGELOG.md | 13 ++++ CONTRIBUTING.md | 5 +- README.it.md | 6 +- README.md | 6 +- .../explanation/adr-bilingual-structural.mdx | 2 +- .../how-to/sovereign-override-404-shield.mdx | 2 +- docs/how-to/add-badges.mdx | 2 +- docs/how-to/configure-ci-cd.mdx | 26 +++++++ .../explanation/adr-bilingual-structural.mdx | 2 +- .../how-to/sovereign-override-404-shield.mdx | 2 +- .../current/how-to/add-badges.mdx | 2 +- .../current/how-to/configure-ci-cd.mdx | 27 +++++++ justfile | 76 ++++++++----------- noxfile.py | 73 ++++++++---------- 15 files changed, 156 insertions(+), 102 deletions(-) diff --git a/CHANGELOG.it.md b/CHANGELOG.it.md index 3c48312..23c640f 100644 --- a/CHANGELOG.it.md +++ b/CHANGELOG.it.md @@ -18,6 +18,20 @@ Le versioni seguono la linea di rilascio di Zenzic Core sotto la Branch Parity R con la release di allineamento infrastrutturale di Zenzic Core (fix della matrice Boundary Testing, floor Mypy abbassato a 3.10). +#### Modificato + +- **Refactoring `noxfile.py` — unificazione pipeline:** Rimossa la sessione nox + `preflight` (duplicava `just verify`; usava `uvx zenzic` senza pin di versione). + Rinominata la sessione `verify-docs` in `verify-codes-parity`. +- **`verify-codes-parity` — Graceful Degradation:** Lo Step 1 ora usa + `ZENZIC_PROJECT_PATH` per i Core Maintainer (sorgente locale via `uv run --project`) + e torna a `uv run --with zenzic` per i contributori esterni (release PyPI + pubblicata). Elimina il percorso sibling hardcoded e il meccanismo `importlib.util`. +- **Aggiornamento `justfile`:** Aggiunta la recipe `verify-codes` + (`uvx nox -s verify-codes-parity`). Aggiornato il target `verify`: + `lint-all typecheck build verify-codes` (la parity dei codici è ora Gate 4 + della pipeline standard). + --- ## [0.7.0] — 2026-05-07 — Quartz Maturity (Stable) diff --git a/CHANGELOG.md b/CHANGELOG.md index 83bc34e..87e8ff1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,19 @@ Versions track the Zenzic Core release line under the Branch Parity Rule. Core infrastructure alignment release (Boundary Testing matrix fix, Mypy floor lowered to 3.10). +#### Changed + +- **`noxfile.py` refactoring — pipeline unification:** Removed `preflight` nox session + (duplicated `just verify`; used bare `uvx zenzic` without version pin). Renamed + `verify-docs` session to `verify-codes-parity`. +- **`verify-codes-parity` — Graceful Degradation:** Step 1 now uses + `ZENZIC_PROJECT_PATH` for Core Maintainers (local source via `uv run --project`) + and falls back to `uv run --with zenzic` for External Contributors (published PyPI + release). Eliminates hardcoded sibling path and `importlib.util` hack. +- **`justfile` update:** Added `verify-codes` recipe (`uvx nox -s verify-codes-parity`). + Updated `verify` target: `lint-all typecheck build verify-codes` (codes parity is + now Gate 4 of the standard pipeline). + --- ## [0.7.0] — 2026-05-07 — Quartz Maturity (Stable) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 00f620b..c34ced6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -217,11 +217,10 @@ For full architecture and lifecycle policy, see Run the full local gate: ```bash -just verify # markdownlint + lint:ts + typecheck + build -just preflight # all pre-commit hooks (mirrors the CI gate exactly) +just verify # all pre-commit hooks + typecheck + build + codes parity (full local gate) ``` -Both must pass with zero errors before you open or update a PR. +This must pass with zero errors before you open or update a PR. ### Pre-commit hooks diff --git a/README.it.md b/README.it.md index 8c11fc6..42a1b7a 100644 --- a/README.it.md +++ b/README.it.md @@ -151,8 +151,8 @@ Cosa fa `just verify`: | `just typecheck` | Prima di aprire/aggiornare la PR | Esegue i controlli TypeScript | | `just build` | Validazione build | Esegue la build di produzione | | `just preview` | Valida l'output costruito | Serve il sito già buildato | -| `just verify` | Controllo locale finale raccomandato | Esegue `markdownlint` + `lint` + `typecheck` + `build` | -| `just preflight` | Prima di ogni commit | Esegue tutti gli hook pre-commit su ogni file tracciato | +| `just verify` | Controllo locale finale raccomandato (gate completo) | Esegue tutti gli hook pre-commit + `typecheck` + `build` + parity dei codici | +| `just lint-all` | Prima di ogni commit | Esegue tutti gli hook pre-commit su ogni file tracciato | | `just reuse` | Dopo aver aggiunto/rinominato file | Verifica la conformità della licenza REUSE/SPDX | | `just sentinel` | Spot-check rapido qualità | Esegue solo la Zenzic Sentinel (più veloce di un preflight completo) | | `just clean` | Pulizia prima di un'esecuzione fresca | Rimuove `build/` e `.docusaurus/` | @@ -194,7 +194,7 @@ Se un hook fallisce, correggi il problema segnalato e ritenta il commit. Per eseguire tutti gli hook manualmente senza committare: ```bash -just preflight +just lint-all ``` ## 7) Workflow CI/CD diff --git a/README.md b/README.md index 206a686..4176d4d 100644 --- a/README.md +++ b/README.md @@ -144,8 +144,8 @@ What `just verify` does: | `just typecheck` | Before opening/updating PR | Runs TypeScript checks | | `just build` | Build validation | Runs production build | | `just preview` | Validate built output | Serves already-built site | -| `just verify` | Recommended final local check | Runs `markdownlint` + `lint` + `typecheck` + `build` | -| `just preflight` | Before every commit | Runs all pre-commit hooks against every tracked file | +| `just verify` | Recommended final local check (full gate) | Runs all pre-commit hooks + `typecheck` + `build` + codes parity | +| `just lint-all` | Before every commit | Runs all pre-commit hooks against every tracked file | | `just reuse` | After adding/renaming files | Checks REUSE/SPDX licence compliance | | `just sentinel` | Quick quality spot-check | Runs the Zenzic Sentinel alone (faster than full preflight) | | `just clean` | Cleanup before fresh run | Removes `build/` and `.docusaurus/` | @@ -187,7 +187,7 @@ If a hook fails, fix the reported issue and retry the commit. To run all hooks manually without committing: ```bash -just preflight +just lint-all ``` ## 7) CI/CD workflows diff --git a/developers/explanation/adr-bilingual-structural.mdx b/developers/explanation/adr-bilingual-structural.mdx index 9955aa9..d60595b 100644 --- a/developers/explanation/adr-bilingual-structural.mdx +++ b/developers/explanation/adr-bilingual-structural.mdx @@ -143,7 +143,7 @@ history noise and make bisect unreliable when investigating regressions. the Italian mirror — this is a non-optional part of the contribution workflow documented in `CONTRIBUTING.md`. -- The `just preflight` recipe (`uvx pre-commit run --all-files`) enforces this +- The `just lint-all` recipe (`uvx pre-commit run --all-files`) enforces this check in CI. A PR that breaks structural symmetry will fail at the gate. diff --git a/developers/how-to/sovereign-override-404-shield.mdx b/developers/how-to/sovereign-override-404-shield.mdx index a02e0fa..d09eea3 100644 --- a/developers/how-to/sovereign-override-404-shield.mdx +++ b/developers/how-to/sovereign-override-404-shield.mdx @@ -76,6 +76,6 @@ If one layer drops the variable, the shield breaks. ## Verification Checklist - `just verify` passes locally with the intended exclusions. -- `just preflight` passes (ensures pre-commit path also honors the variable). +- `just lint-all` passes (ensures pre-commit path also honors the variable). - CI env includes only the minimum `--exclude-url` entries required. - Follow-up issue/PR exists to remove temporary exclusions post-launch. diff --git a/docs/how-to/add-badges.mdx b/docs/how-to/add-badges.mdx index 70a8e20..3574001 100644 --- a/docs/how-to/add-badges.mdx +++ b/docs/how-to/add-badges.mdx @@ -128,4 +128,4 @@ Projects in air-gapped or enterprise environments that cannot call `img.shields. **Note:** `brand-kit.zip` is a build artifact. It is not stored in the repository — download it from the [GitHub Releases](https://github.com/PythonWoods/zenzic/releases/latest) page, or -generate it locally with `nox -s preflight`. +generate it locally with `nox -s build`. diff --git a/docs/how-to/configure-ci-cd.mdx b/docs/how-to/configure-ci-cd.mdx index 888dd1f..abdc01d 100644 --- a/docs/how-to/configure-ci-cd.mdx +++ b/docs/how-to/configure-ci-cd.mdx @@ -437,3 +437,29 @@ repos: With this hook, `git commit` will refuse to proceed if Zenzic detects a credential, a broken link, or any exit-1 quality finding. The feedback is instant, the fix is local, and the secret never touches the remote. + +--- + +## Doc-Code Parity {#doc-code-parity} + +Every Zxxx finding code documented in `docs/` must have a registered entry in +`src/zenzic/core/codes.py` in the core package — and vice versa. This bidirectional +invariant is enforced by the `verify-codes-parity` Nox session: + +```bash +# Run standalone +nox -s verify-codes-parity + +# Runs automatically as part of the full local gate +just verify +``` + +The session uses **Graceful Degradation** to locate `codes.py`: + +| Condition | Strategy | Command used | +|:----------|:---------|:-------------| +| `ZENZIC_PROJECT_PATH` set, or `../zenzic` exists | **Core Maintainer** — uses local source tree | `uv run --project python -c ...` | +| Local core not found | **External Contributor** — uses published PyPI release | `uv run --with zenzic python -c ...` | + +This means external contributors can run `nox -s verify-codes-parity` with no local +checkout of the core repository — the published `zenzic` package on PyPI is sufficient. diff --git a/i18n/it/docusaurus-plugin-content-docs-developers/current/explanation/adr-bilingual-structural.mdx b/i18n/it/docusaurus-plugin-content-docs-developers/current/explanation/adr-bilingual-structural.mdx index 3692f2a..5a68345 100644 --- a/i18n/it/docusaurus-plugin-content-docs-developers/current/explanation/adr-bilingual-structural.mdx +++ b/i18n/it/docusaurus-plugin-content-docs-developers/current/explanation/adr-bilingual-structural.mdx @@ -144,7 +144,7 @@ regressioni. consapevole dello specchio italiano — questa è una parte non opzionale del workflow di contribuzione documentato in `CONTRIBUTING.md`. -- La recipe `just preflight` (`uvx pre-commit run --all-files`) applica questo +- La recipe `just lint-all` (`uvx pre-commit run --all-files`) applica questo controllo in CI. Una PR che rompe la simmetria strutturale fallirà al gate. diff --git a/i18n/it/docusaurus-plugin-content-docs-developers/current/how-to/sovereign-override-404-shield.mdx b/i18n/it/docusaurus-plugin-content-docs-developers/current/how-to/sovereign-override-404-shield.mdx index 2da8c34..9e512f8 100644 --- a/i18n/it/docusaurus-plugin-content-docs-developers/current/how-to/sovereign-override-404-shield.mdx +++ b/i18n/it/docusaurus-plugin-content-docs-developers/current/how-to/sovereign-override-404-shield.mdx @@ -76,6 +76,6 @@ Se un layer perde la variabile, lo scudo si rompe. ## Checklist di Verifica - `just verify` passa in locale con le esclusioni previste. -- `just preflight` passa (conferma che anche il percorso pre-commit rispetta la variabile). +- `just lint-all` passa (conferma che anche il percorso pre-commit rispetta la variabile). - L'env CI contiene solo le voci `--exclude-url` strettamente necessarie. - Esiste issue/PR di follow-up per rimuovere le esclusioni temporanee dopo il lancio. diff --git a/i18n/it/docusaurus-plugin-content-docs/current/how-to/add-badges.mdx b/i18n/it/docusaurus-plugin-content-docs/current/how-to/add-badges.mdx index d537b18..581c4ec 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/how-to/add-badges.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/how-to/add-badges.mdx @@ -128,4 +128,4 @@ I progetti in ambienti air-gapped o aziendali che non possono chiamare `img.shie **Nota:** `brand-kit.zip` è un artefatto di build. Non è archiviato nel repository — scaricalo dalla pagina [GitHub Releases](https://github.com/PythonWoods/zenzic/releases/latest), oppure -generalo in locale con `nox -s preflight`. +generalo in locale con `nox -s build`. diff --git a/i18n/it/docusaurus-plugin-content-docs/current/how-to/configure-ci-cd.mdx b/i18n/it/docusaurus-plugin-content-docs/current/how-to/configure-ci-cd.mdx index f38625f..c7d8c64 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/how-to/configure-ci-cd.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/how-to/configure-ci-cd.mdx @@ -440,3 +440,30 @@ repos: Con questo hook, `git commit` si rifiuterà di procedere se Zenzic rileva una credenziale, un link rotto o qualsiasi finding di qualità con exit 1. Il feedback è istantaneo, la correzione è locale, e il segreto non tocca mai il remoto. + +--- + +## Parity Doc-Code {#doc-code-parity} + +Ogni codice di finding Zxxx documentato in `docs/` deve avere un'entità registrata in +`src/zenzic/core/codes.py` nel pacchetto core — e viceversa. Questo invariante +bidirezionale è applicato dalla sessione Nox `verify-codes-parity`: + +```bash +# Esecuzione autonoma +nox -s verify-codes-parity + +# Esegue automaticamente come parte del gate locale completo +just verify +``` + +La sessione usa la **Graceful Degradation** per localizzare `codes.py`: + +| Condizione | Strategia | Comando usato | +|:-----------|:---------|:--------------| +| `ZENZIC_PROJECT_PATH` impostato, o `../zenzic` esiste | **Core Maintainer** — usa il source tree locale | `uv run --project python -c ...` | +| Core locale non trovato | **External Contributor** — usa il rilascio PyPI pubblicato | `uv run --with zenzic python -c ...` | + +Questo significa che i contributori esterni possono eseguire `nox -s verify-codes-parity` +senza un checkout locale del repository core — il pacchetto `zenzic` pubblicato su +PyPI è sufficiente. diff --git a/justfile b/justfile index 707c07f..1eefc2e 100644 --- a/justfile +++ b/justfile @@ -1,12 +1,8 @@ # SPDX-FileCopyrightText: 2026 PythonWoods # SPDX-License-Identifier: Apache-2.0 -# just - Obsidian Enterprise workflow for zenzic-doc -set shell := ["bash", "-c"] -# ZRT-010 — Unified Registry: zenzic is resolved from PyPI via uvx, mirroring CI exactly. -# Override for local dev against a monorepo checkout: -# ZENZIC_CORE_REF=/path/to/local/zenzic just check -core_ref := env_var_or_default("ZENZIC_CORE_REF", "zenzic==v0.7.0") +# just - Quartz Enterprise workflow for zenzic-doc +set shell :=["bash", "-c"] # Use `just --list` to see available commands @@ -20,7 +16,7 @@ setup: clean: rm -rf build .docusaurus -# Deep clean: remove artifacts and node_modules (preserves package-lock.json for reproducible npm ci) +# Deep clean: remove artifacts and node_modules clean-all: clean rm -rf node_modules @@ -33,11 +29,10 @@ purge-cache: # --- DEVELOPMENT --- # Start local development server (single-locale; locale dropdown inactive in dev mode) -# Use 'just preview' to test the locale switcher in a full production environment start: npm run start -# Start local development server in Italian (single-locale dev mode) +# Start local development server in Italian start-it: npm run start:it @@ -45,29 +40,31 @@ start-it: serve: npm run serve -# Build then serve production site locally (full EN+IT testbed — recommended for locale switcher testing) +# Build then serve production site locally (full EN+IT testbed) preview: build npm run serve # --- QUALITY GATES --- -# Build production static site — Sentinel Gate: Zenzic must pass before Docusaurus builds -build: sentinel - npm run build +# Fast local checks (pre-commit on staged files) +lint *args: + uvx pre-commit run {{args}} + +# Recommended final local check (4-Gates Standard: pre-commit + typecheck + build + codes parity) +verify: lint-all typecheck build verify-codes + +# Verify Zxxx code parity between codes.py and finding-codes.mdx (EN + IT) +verify-codes: + uvx nox -s verify-codes-parity -# Run the Zenzic Sentinel quality check only (faster than full preflight). -# ZRT-010: delegates to 'just check' — single source of truth for the guard. -# Pass extra flags directly: just sentinel --no-external -sentinel *args: - just check {{args}} +# --- INTERNAL RECIPES (Hidden from 'just --list') --- -# Run all pre-commit hooks against every tracked file (mirrors CI gate exactly) -preflight: +lint-all: uvx pre-commit run --all-files -# Explicit Zenzic audit gate (ZRT-010 — Sovereign Parity). -# Pre-Launch Guard is inlined: local == CI. No env var required. -# Pass extra flags directly: just check --no-external +build: check + npm run build + check *args: #!/usr/bin/env bash set -euo pipefail @@ -75,42 +72,31 @@ check *args: GUARD=( --exclude-url "https://www.contributor-covenant.org/version/2/1/code_of_conduct.html" ) - uvx --from "{{core_ref}}" zenzic check all --strict "${GUARD[@]}" {{args}} - -# Static type check + CORE_PATH="${ZENZIC_PROJECT_PATH:-../zenzic}" + + if[ -d "$CORE_PATH" ]; then + echo "🛡️ [Zenzic Sentinel] Local core detected. Using: $CORE_PATH" + uv run --project "$CORE_PATH" zenzic check all --strict "${GUARD[@]}" {{args}} + else + echo "🛡️ [Zenzic Sentinel] Local core not found. Using published PyPI release..." + uvx zenzic@0.7.0 check all --strict "${GUARD[@]}" {{args}} + fi typecheck: npm run typecheck -# Lint TypeScript/React source files (excluding intentional landing monolith) -lint: +lint-ts: npm run lint:ts -# Lint Markdown and MDX files markdownlint: npm run lint:md -# Test suite (docs integration checks via nox) -test: - uvx nox -s tests - -# Enterprise local gate (4-Gates Standard) -verify: check preflight test - -# --- PROJECT ADMIN --- - -# Check REUSE/SPDX licence compliance reuse: uvx reuse lint -# Bump all hardcoded Zenzic version references -# Usage: just bump 0.6.3 -# just bump 0.6.3 'v0.6.3 "Obsidian Flux" Stable' bump version badge='': @bash scripts/bump-version.sh "{{version}}" "{{badge}}" -# Check developer environment health (node, npm, uv, zenzic) doctor: @node -v || echo "node missing" @npm -v || echo "npm missing" - @uv --version || echo "uv missing" - @uvx zenzic --version 2>/dev/null || echo "zenzic not cached (first run: uvx zenzic --version)" + @uv --version || echo "uv missing" \ No newline at end of file diff --git a/noxfile.py b/noxfile.py index ca7c6c9..9daafa7 100644 --- a/noxfile.py +++ b/noxfile.py @@ -6,11 +6,10 @@ Python-based tooling (REUSE compliance). Quick reference: - nox -s typecheck — Static type checking (tsc) - nox -s build — Production build (EN + IT) - nox -s reuse — REUSE/SPDX licence compliance - nox -s verify-docs — Doc-Code Validator: Zxxx parity between .mdx and codes.py - nox -s preflight — Full CI-equivalent pipeline (includes Zenzic quality gate) + nox -s typecheck — Static type checking (tsc) + nox -s build — Production build (EN + IT) + nox -s reuse — REUSE/SPDX licence compliance + nox -s verify-codes-parity — Doc-Code Validator: Zxxx parity between .mdx and codes.py """ import nox @@ -46,58 +45,48 @@ def reuse(session: nox.Session) -> None: session.run("uvx", "reuse", "lint", external=True) -@nox.session(venv_backend="none") -def preflight(session: nox.Session) -> None: - """Full CI-equivalent pipeline: typecheck → build → reuse → zenzic.""" - session.run("npm", "run", "typecheck", external=True) - session.run("npm", "run", "build", external=True) - session.run("uvx", "reuse", "lint", external=True) - session.run("uvx", "zenzic", "check", "all", "--strict", external=True) - - -@nox.session(name="verify-docs", venv_backend="none") -def verify_docs(session: nox.Session) -> None: +@nox.session(name="verify-codes-parity", venv_backend="none") +def verify_codes_parity(session: nox.Session) -> None: """Doc-Code Validator: verify every Zxxx code in .mdx files exists in codes.py. Scans all .mdx files under docs/ and i18n/ for Zxxx patterns and cross-checks them against the canonical CODE_NAMES registry in the core package. Exits non-zero if any undocumented code is found in the docs, or any registered code is absent from finding-codes.mdx — ensuring documentation and code stay in perfect parity. + + Graceful Degradation: + - Core Maintainer: ZENZIC_PROJECT_PATH set (or ../zenzic exists) → uses local source. + - External Contributor: local core not found → uses published PyPI release. """ + import os import re import subprocess - import sys from pathlib import Path root = Path(__file__).parent - # ── Step 1: Load canonical codes from the installed core package ────────── - result = subprocess.run( - [ - sys.executable, - "-c", - ( - "import sys; sys.path.insert(0, 'src'); " - "from zenzic.core.codes import CODE_NAMES; " - "print('\\n'.join(sorted(CODE_NAMES.keys())))" - ), - ], - capture_output=True, - text=True, + # ── Step 1: Load canonical codes — Graceful Degradation ─────────────────── + core_path = os.environ.get("ZENZIC_PROJECT_PATH", "../zenzic") + python_snippet = ( + "from zenzic.core.codes import CODE_NAMES; " + "print('\\n'.join(sorted(CODE_NAMES.keys())))" ) + + if os.path.exists(core_path): + # Core Maintainer: run against local source tree + session.log(f"[Zenzic] Local core detected at '{core_path}' — using local source.") + cmd = ["uv", "run", "--project", core_path, "python", "-c", python_snippet] + else: + # External Contributor: fall back to published PyPI release + session.log("[Zenzic] Local core not found — using published PyPI release.") + cmd = ["uv", "run", "--with", "zenzic", "python", "-c", python_snippet] + + result = subprocess.run(cmd, capture_output=True, text=True) if result.returncode != 0: - # Try uvx fallback — codes.py may live in a sibling repo - codes_path = root.parent / "zenzic" / "src" / "zenzic" / "core" / "codes.py" - if not codes_path.exists(): - session.warn("codes.py not found — skipping core→doc direction check") - canonical: set[str] = set() - else: - import importlib.util - - spec = importlib.util.spec_from_file_location("codes", codes_path) - mod = importlib.util.module_from_spec(spec) # type: ignore[arg-type] - spec.loader.exec_module(mod) # type: ignore[union-attr] - canonical = set(mod.CODE_NAMES.keys()) + session.warn( + f"Could not load codes.py: {result.stderr.strip()} — skipping core→doc direction check" + ) + canonical: set[str] = set() else: canonical = set(result.stdout.strip().splitlines()) From 8867b41f9757bad194ecfcf7c6bebc7852b2801b Mon Sep 17 00:00:00 2001 From: PythonWoods-Dev Date: Fri, 8 May 2026 10:12:52 +0200 Subject: [PATCH 03/18] =?UTF-8?q?fix(justfile):=20add=20missing=20space=20?= =?UTF-8?q?in=20bash=20if-test=20=E2=80=94=20if[=20=E2=86=92=20if=20[?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Silent syntax error in the 'check' recipe: bash treats 'if[' as a command name rather than the 'if' keyword followed by '['. The command would fail with 'command not found: if[-d' on first execution. --- justfile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/justfile b/justfile index 1eefc2e..1a4926b 100644 --- a/justfile +++ b/justfile @@ -74,7 +74,7 @@ check *args: ) CORE_PATH="${ZENZIC_PROJECT_PATH:-../zenzic}" - if[ -d "$CORE_PATH" ]; then + if [ -d "$CORE_PATH" ]; then echo "🛡️ [Zenzic Sentinel] Local core detected. Using: $CORE_PATH" uv run --project "$CORE_PATH" zenzic check all --strict "${GUARD[@]}" {{args}} else From 3535800b46094cb534469ca484e6a5417d0ea3f7 Mon Sep 17 00:00:00 2001 From: PythonWoods-Dev Date: Fri, 8 May 2026 12:42:21 +0200 Subject: [PATCH 04/18] =?UTF-8?q?feat(dx):=20Sprint=20D101=20=E2=80=94=20?= =?UTF-8?q?=5Fcheck-hooks=20guard=20+=20ecosystem.mdx=20transparency=20(EN?= =?UTF-8?q?+IT)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - _check-hooks: warn if pre-push hook not installed (warn-only, never blocks) - ecosystem.mdx: retitled 'The Zenzic Ecosystem'; added: - Ecosystem at a Glance table (Core / Structum / Zenzic-Doc) - zenzic-doc Living Test Bench section (self-dogfooding, Graceful Degradation) - The 4-Gates Standard section (IDE / Pre-commit / Pre-push / Remote CI) - IT mirror updated atomically --- CHANGELOG.it.md | 9 +++ CHANGELOG.md | 9 +++ docs/explanation/ecosystem.mdx | 57 +++++++++++++++++- .../current/explanation/ecosystem.mdx | 59 +++++++++++++++++-- justfile | 11 +++- 5 files changed, 136 insertions(+), 9 deletions(-) diff --git a/CHANGELOG.it.md b/CHANGELOG.it.md index 23c640f..39ddcb2 100644 --- a/CHANGELOG.it.md +++ b/CHANGELOG.it.md @@ -17,6 +17,15 @@ Le versioni seguono la linea di rilascio di Zenzic Core sotto la Branch Parity R in questo repository (ecosistema Node/Docusaurus). Questa voce traccia l'allineamento con la release di allineamento infrastrutturale di Zenzic Core (fix della matrice Boundary Testing, floor Mypy abbassato a 3.10). +- **DX guard `_check-hooks`:** Aggiunta recipe nascosta `_check-hooks` come prima dipendenza + di `just verify` in tutti e quattro i repository dell'ecosistema. Emette un avviso se + l'hook Final Guard pre-push (`pre-commit install -t pre-push`) non è installato + localmente, senza bloccare l'esecuzione della verifica. +- **`ecosystem.mdx` — Trasparenza Ecosistema (Sprint D101):** Pagina rinominata "L'Ecosistema + Zenzic". Aggiunte tre nuove sezioni: "L'Ecosistema in Sintesi" (tabella dei ruoli Core / + Structum / Zenzic-Doc), "zenzic-doc — Banco di Prova Vivente" (self-dogfooding, Graceful + Degradation, `verify-codes-parity`), "Lo Standard a 4 Cancelli" (IDE / Pre-commit / + Pre-push / CI Remota). EN + IT aggiornati atomicamente. #### Modificato diff --git a/CHANGELOG.md b/CHANGELOG.md index 87e8ff1..236c688 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,15 @@ Versions track the Zenzic Core release line under the Branch Parity Rule. repository (Node/Docusaurus ecosystem). This entry tracks alignment with the Zenzic Core infrastructure alignment release (Boundary Testing matrix fix, Mypy floor lowered to 3.10). +- **`_check-hooks` DX guard:** Added hidden `_check-hooks` recipe as first dependency of + `just verify` across all four ecosystem repositories. Emits a warning if the pre-push + Final Guard hook (`pre-commit install -t pre-push`) is not installed locally, without + blocking the verification run. +- **`ecosystem.mdx` — Ecosystem Transparency (Sprint D101):** Page retitled “The Zenzic + Ecosystem”. Added three new sections: “The Ecosystem at a Glance” (Core / Structum / + Zenzic-Doc role table), “zenzic-doc — Living Test Bench” (self-dogfooding, Graceful + Degradation, `verify-codes-parity`), and “The 4-Gates Standard” (IDE / Pre-commit / + Pre-push / Remote CI). EN + IT updated atomically. #### Changed diff --git a/docs/explanation/ecosystem.mdx b/docs/explanation/ecosystem.mdx index 455bce0..893f0fc 100644 --- a/docs/explanation/ecosystem.mdx +++ b/docs/explanation/ecosystem.mdx @@ -1,10 +1,22 @@ --- sidebar_position: 1 -title: The Adapter Model -description: How Zenzic understands any documentation engine without becoming part of it — the Adapter protocol and the Sovereign CLI strategy. +title: The Zenzic Ecosystem +description: Zenzic Core, Structum, and zenzic-doc — the ecosystem architecture, the Adapter protocol, and the 4-Gates Standard for documentation quality. --- -# The Adapter Model +# The Zenzic Ecosystem + +## The Ecosystem at a Glance {#ecosystem-at-a-glance} + +| Component | Role | +| :--- | :--- | +| **Zenzic Core** | The pure, agnostic, Zero-Config linter. One binary. Every documentation engine. | +| **Structum** | Optional MCP interface that supplies architectural context to AI coding assistants. | +| **Zenzic-Doc** | The living test bench — a self-validating Docusaurus site that dogfoods every Zenzic release. | + +Each component is independently installable and has no hard dependency on the others. + +--- Zenzic operates as a **sovereign external auditor**. It never embeds itself inside a build engine, never spawns subprocesses, and never requires engine-specific installation extras. @@ -121,6 +133,45 @@ Zenzic runs **before or after** the build — never inside it. This gives you: --- +## zenzic-doc — Living Test Bench {#living-test-bench} + +The Zenzic documentation site (`zenzic-doc`) is not a passive artifact — it is an active +participant in the quality pipeline. Every commit runs `zenzic check all --strict` against +itself before it can be pushed (Sovereign Parity, ZRT-010). + +Beyond the standard Zenzic audit, `zenzic-doc` enforces a second invariant unique to its +role as documentation for a linter: every Zxxx finding code present in `docs/` must have a +registered entry in `src/zenzic/core/codes.py` in the Core package — and vice versa. This +bidirectional parity is enforced by the `verify-codes-parity` Nox session via **Graceful +Degradation**: + +- **Core Maintainer**: `ZENZIC_PROJECT_PATH` set → `uv run --project ` against local source. +- **External Contributor**: local core absent → `uv run --with zenzic` against the published PyPI release. + +Running `just verify` in `zenzic-doc` executes all four gates in sequence. External contributors +need no local checkout of Zenzic Core. + +--- + +## The 4-Gates Standard {#4-gates-standard} + +Every repository in the Zenzic ecosystem enforces quality at four progressive checkpoints: + +| Gate | Trigger | Tool | What it catches | +| :--- | :--- | :--- | :--- | +| **Gate 1 — IDE** | Real-time, on save | Editor extensions (Pylance, ESLint) | Type errors, syntax issues | +| **Gate 2 — Pre-commit** | `git commit` | `pre-commit` hooks | Lint, credentials, formatting, REUSE | +| **Gate 3 — Pre-push** | `git push` | `just verify` (via `pre-commit -t pre-push`) | Full validation suite identical to CI | +| **Gate 4 — Remote CI** | Pull Request / push | GitHub Actions | Identical `just verify` on a clean Ubuntu runner | + +Gates 3 and 4 execute the **same command** (`just verify`) — local and remote are never +allowed to drift. This is the Sovereign Parity principle (ZRT-010). + +> For operational setup (installing hooks, workflow YAML), see the +> [CI/CD Integration guide](../how-to/configure-ci-cd#doc-code-parity). + +--- + ## Choosing the Right Model {#choosing} | Scenario | Recommended approach | diff --git a/i18n/it/docusaurus-plugin-content-docs/current/explanation/ecosystem.mdx b/i18n/it/docusaurus-plugin-content-docs/current/explanation/ecosystem.mdx index ee09238..3c0cf2e 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/explanation/ecosystem.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/explanation/ecosystem.mdx @@ -1,11 +1,23 @@ --- sidebar_position: 1 -sidebar_label: "Modello Adapter" -title: Il Modello Adapter -description: Come Zenzic comprende qualsiasi motore di documentazione senza farne parte — il protocollo Adapter e la strategia CLI Sovrana. +sidebar_label: "Ecosistema Zenzic" +title: L'Ecosistema Zenzic +description: Zenzic Core, Structum e zenzic-doc — l'architettura dell'ecosistema, il protocollo Adapter e lo Standard a 4 Cancelli per la qualità della documentazione. --- -# Il Modello Adapter +# L'Ecosistema Zenzic + +## L'Ecosistema in Sintesi {#ecosystem-at-a-glance} + +| Componente | Ruolo | +| :--- | :--- | +| **Zenzic Core** | Il linter puro, agnostico, Zero-Config. Un solo binario. Ogni motore di documentazione. | +| **Structum** | Interfaccia MCP opzionale che fornisce contesto architetturale agli assistenti AI per la programmazione. | +| **Zenzic-Doc** | Il banco di prova vivente — un sito Docusaurus auto-validante che testa ogni release di Zenzic su sé stesso. | + +Ogni componente è installabile indipendentemente e non ha dipendenze rigide dagli altri. + +--- Zenzic opera come **revisore esterno sovrano**. Non si incorpora mai all'interno di un motore di build, non avvia mai sottoprocessi e non richiede mai extra di installazione specifici per il motore. @@ -123,6 +135,45 @@ Zenzic viene eseguito **prima o dopo** la build — mai al suo interno. Questo g --- +## zenzic-doc — Banco di Prova Vivente {#living-test-bench} + +Il sito di documentazione Zenzic (`zenzic-doc`) non è un artefatto passivo — è un +partecipante attivo nella pipeline di qualità. Ogni commit esegue `zenzic check all --strict` +contro sé stesso prima di poter essere inviato (Sovereign Parity, ZRT-010). + +Oltre all'audit standard di Zenzic, `zenzic-doc` impone un secondo invariante unico al suo +ruolo di documentazione di un linter: ogni codice di finding Zxxx presente in `docs/` deve +avere un'entità registrata in `src/zenzic/core/codes.py` nel pacchetto Core — e viceversa. +Questa parità bidirezionale è applicata dalla sessione Nox `verify-codes-parity` tramite +**Graceful Degradation**: + +- **Core Maintainer**: `ZENZIC_PROJECT_PATH` impostato → `uv run --project ` sul sorgente locale. +- **External Contributor**: core locale assente → `uv run --with zenzic` sulla release PyPI pubblicata. + +Eseguire `just verify` in `zenzic-doc` avvia tutti e quattro i gate in sequenza. I contributori +esteri non hanno bisogno di un checkout locale di Zenzic Core. + +--- + +## Lo Standard a 4 Cancelli {#4-gates-standard} + +Ogni repository dell'ecosistema Zenzic impone la qualità in quattro checkpoint progressivi: + +| Cancello | Trigger | Strumento | Cosa rileva | +| :--- | :--- | :--- | :--- | +| **Cancello 1 — IDE** | In tempo reale, al salvataggio | Estensioni editor (Pylance, ESLint) | Errori di tipo, problemi sintattici | +| **Cancello 2 — Pre-commit** | `git commit` | Hook `pre-commit` | Lint, credenziali, formattazione, REUSE | +| **Cancello 3 — Pre-push** | `git push` | `just verify` (via `pre-commit -t pre-push`) | Suite di validazione completa identica alla CI | +| **Cancello 4 — CI Remota** | Pull Request / push | GitHub Actions | `just verify` identico su un runner Ubuntu pulito | + +I Cancelli 3 e 4 eseguono lo **stesso comando** (`just verify`) — locale e remoto non possono +mai divergere. Questo è il principio di Sovereign Parity (ZRT-010). + +> Per la configurazione operativa (installazione hook, YAML del workflow), vedi la +> [guida CI/CD Integration](../how-to/configure-ci-cd#doc-code-parity). + +--- + ## Scegliere il Modello Giusto {#choosing} | Scenario | Approccio consigliato | diff --git a/justfile b/justfile index 1a4926b..f9f760c 100644 --- a/justfile +++ b/justfile @@ -51,7 +51,7 @@ lint *args: uvx pre-commit run {{args}} # Recommended final local check (4-Gates Standard: pre-commit + typecheck + build + codes parity) -verify: lint-all typecheck build verify-codes +verify: _check-hooks lint-all typecheck build verify-codes # Verify Zxxx code parity between codes.py and finding-codes.mdx (EN + IT) verify-codes: @@ -99,4 +99,11 @@ bump version badge='': doctor: @node -v || echo "node missing" @npm -v || echo "npm missing" - @uv --version || echo "uv missing" \ No newline at end of file + @uv --version || echo "uv missing" + +_check-hooks: + #!/usr/bin/env bash + if [ ! -f .git/hooks/pre-push ]; then + echo "⚠️ WARNING: Pre-push hook not installed — commits are unprotected before push." + echo "👉 Run: pre-commit install -t pre-push" + fi \ No newline at end of file From e5d11e3b1cc7cd2fb42ae0d00b6a4f57e912654b Mon Sep 17 00:00:00 2001 From: PythonWoods-Dev Date: Fri, 8 May 2026 15:34:46 +0200 Subject: [PATCH 05/18] =?UTF-8?q?fix(dx):=20Sprint=20D102=20=E2=80=94=20Z9?= =?UTF-8?q?07=20docs,=20double=20execution,=20phantom=20codes=20(EN+IT)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - _check-hooks: empathetic DX Polish (ANSI yellow, uvx fix command) - justfile: remove double execution (typecheck + check removed from verify chain) - codes.py: Z000 now canonical (34 codes total) - finding-codes.mdx: add Z907 I18N_PARITY section (EN+IT) - finding-codes.mdx: purge Legacy Codes section; promote CI/CD to H2 - checks.mdx: Z001→Z101, Z002→Z103, Z009→Z902 verify-codes-parity: 0 MISSING, 0 phantom codes --- CHANGELOG.it.md | 16 +++++++ CHANGELOG.md | 18 +++++++- docs/reference/checks.mdx | 14 +++--- docs/reference/finding-codes.mdx | 43 ++++++++---------- .../current/reference/finding-codes.mdx | 44 ++++++++----------- justfile | 16 ++++--- 6 files changed, 86 insertions(+), 65 deletions(-) diff --git a/CHANGELOG.it.md b/CHANGELOG.it.md index 39ddcb2..c99de38 100644 --- a/CHANGELOG.it.md +++ b/CHANGELOG.it.md @@ -26,6 +26,10 @@ Le versioni seguono la linea di rilascio di Zenzic Core sotto la Branch Parity R Structum / Zenzic-Doc), "zenzic-doc — Banco di Prova Vivente" (self-dogfooding, Graceful Degradation, `verify-codes-parity`), "Lo Standard a 4 Cancelli" (IDE / Pre-commit / Pre-push / CI Remota). EN + IT aggiornati atomicamente. +- **`Z907 I18N_PARITY` — voce enciclopedia finding-codes.mdx (Sprint D102):** Aggiunta + sezione `{#z907}` dedicata a `finding-codes.mdx` (EN + IT) che documenta il controllo + di Parità I18n: invariante di presenza del mirror e invariante di parità frontmatter. + Risolve l’errore MISSING di `verify-codes-parity` per Z907. Simmetria bilingue ripristinata. #### Modificato @@ -40,6 +44,18 @@ Le versioni seguono la linea di rilascio di Zenzic Core sotto la Branch Parity R (`uvx nox -s verify-codes-parity`). Aggiornato il target `verify`: `lint-all typecheck build verify-codes` (la parity dei codici è ora Gate 4 della pipeline standard). +- **`_check-hooks` — DX Polish (Sprint D102):** Aggiornato il copy del warning: colore + ANSI giallo, riga esplicativa del “perché conta” e `uvx pre-commit install -t pre-push` + (zero installazioni globali richieste). Applicato in tutti e quattro i repository. +- **Doppia Esecuzione eliminata — pipeline `just verify` (Sprint D102):** Rimosso + `typecheck` ridondante dalla catena `verify` (gira già in `lint-all`/pre-commit). + Rimossa la dipendenza `check` dalla recipe `build` (Zenzic Sentinel gira già in + `lint-all`/pre-commit). Catena `verify`: `_check-hooks lint-all build verify-codes`. +- **`finding-codes.mdx` — sezione Legacy rimossa (Sprint D102):** Sezione `## Codici + Legacy [Deprecati]` (codici pre-v0.6.0 Z001/Z002/Z009) rimossa. Z000 promosso a + codice canonico in `codes.py`. `## Integrazione con CI/CD` promossa da H3 a H2. +- **`docs/reference/checks.mdx` — modernizzazione codici canonici (Sprint D102):** + Riferimenti legacy aggiornati: `Z001`→`Z101`, `Z002`→`Z103`, `Z009`→`Z902`. --- diff --git a/CHANGELOG.md b/CHANGELOG.md index 236c688..aeea465 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -25,8 +25,10 @@ Versions track the Zenzic Core release line under the Branch Parity Rule. Ecosystem”. Added three new sections: “The Ecosystem at a Glance” (Core / Structum / Zenzic-Doc role table), “zenzic-doc — Living Test Bench” (self-dogfooding, Graceful Degradation, `verify-codes-parity`), and “The 4-Gates Standard” (IDE / Pre-commit / - Pre-push / Remote CI). EN + IT updated atomically. - + Pre-push / Remote CI). EN + IT updated atomically.- **`Z907 I18N_PARITY` — finding-codes.mdx encyclopedia entry (Sprint D102):** Added + dedicated `{#z907}` section to `finding-codes.mdx` (EN + IT) documenting the I18n + Parity check: mirror-presence and frontmatter-parity invariants. Resolves + `verify-codes-parity` MISSING error for Z907. Bilingual symmetry restored. #### Changed - **`noxfile.py` refactoring — pipeline unification:** Removed `preflight` nox session @@ -39,6 +41,18 @@ Versions track the Zenzic Core release line under the Branch Parity Rule. - **`justfile` update:** Added `verify-codes` recipe (`uvx nox -s verify-codes-parity`). Updated `verify` target: `lint-all typecheck build verify-codes` (codes parity is now Gate 4 of the standard pipeline). +- **`_check-hooks` — DX Polish (Sprint D102):** Updated warning copy: ANSI yellow colour, + explanatory “why it matters” line, and `uvx pre-commit install -t pre-push` (zero global + install required). Applied across all four ecosystem repositories. +- **Double Execution eliminated — `just verify` pipeline (Sprint D102):** Removed redundant + `typecheck` from `verify` chain (already runs inside `lint-all`/pre-commit). Removed + `check` dependency from `build` recipe (Zenzic Sentinel already runs inside + `lint-all`/pre-commit). `verify` chain: `_check-hooks lint-all build verify-codes`. +- **`finding-codes.mdx` — Legacy section purged (Sprint D102):** `## Legacy Codes + [Deprecated]` section (Z001/Z002/Z009 pre-v0.6.0 codes) removed. Z000 promoted to + canonical code in `codes.py`. `## Integration with CI/CD` promoted from H3 to H2. +- **`docs/reference/checks.mdx` — canonical code modernization (Sprint D102):** + Legacy references updated: `Z001`→`Z101`, `Z002`→`Z103`, `Z009`→`Z902`. --- diff --git a/docs/reference/checks.mdx b/docs/reference/checks.mdx index 7ff45c8..ece71c3 100644 --- a/docs/reference/checks.mdx +++ b/docs/reference/checks.mdx @@ -54,9 +54,9 @@ Each route carries a status that tells Zenzic how to treat links pointing to it: | Status | Meaning | Link result | | :--- | :--- | :--- | | `REACHABLE` | Page is listed in navigation or is a locale route | Valid | -| `ORPHAN_BUT_EXISTING` | File exists on disk but is not in site navigation | Z002 warning | -| `IGNORED` | Excluded by configuration (e.g. README files, private directories) | Z001 error | -| `CONFLICT` | Two source files produce the same canonical URL | Z001 error | +| `ORPHAN_BUT_EXISTING` | File exists on disk but is not in site navigation | Z103 warning | +| `IGNORED` | Excluded by configuration (e.g. README files, private directories) | Z101 error | +| `CONFLICT` | Two source files produce the same canonical URL | Z101 error | **Why this matters:** A file can exist on your filesystem and still be `IGNORED` in the VSM. A URL can be `REACHABLE` in the VSM without having a corresponding file on disk (for example, locale index routes). The VSM is the authority — Zenzic checks reachability, not just file existence. @@ -98,11 +98,11 @@ validate_same_page_anchors = true | Code | Severity | Meaning | | :--- | :---: | :--- | -| `Z001` | error | **Broken link** — target does not exist in the VSM | -| `Z002` | warning | **Orphan link** — target exists on disk but not in site navigation | +| `Z101` | error | **Broken link** — target does not exist in the VSM | +| `Z103` | warning | **Orphan link** — target exists on disk but not in site navigation | | `ABSOLUTE_PATH` | error | **Absolute path** — link uses a site-absolute path (`/docs/page`) instead of a relative path (`../page`) | -`Z001` always blocks the pipeline (exit code 1). `Z002` is a warning — it appears in the report but does not fail CI unless `--strict` is passed. `ABSOLUTE_PATH` is an error because absolute paths break portability when a site is hosted in a subdirectory. +`Z101` always blocks the pipeline (exit code 1). `Z103` is a warning — it appears in the report but does not fail CI unless `--strict` is passed. `ABSOLUTE_PATH` is an error because absolute paths break portability when a site is hosted in a subdirectory. :::note[Physical Consistency — why relative paths matter] @@ -158,7 +158,7 @@ The two streams have opposite filtering rules by design. The Content stream must **Pre-Scan Normalizer.** Before running detection patterns, the Shield normalises each line to defeat obfuscation. Inline code backticks are unwrapped, concatenation operators are removed, and table pipe characters are collapsed. This means a secret broken across Markdown table columns — such as an AWS key split into `` `AKIA` + `suffix` `` — is reassembled before scanning. Both the raw and normalised forms are checked, and a deduplication set prevents double-reporting. -**ReDoS Protection.** If you add custom regex patterns via `[[custom_rules]]` in `zenzic.toml`, Zenzic stress-tests each pattern with a 100 ms canary before it ever runs against your files. Patterns that exhibit catastrophic backtracking are rejected at startup with a clear error. As a second safety net, every worker process has a 30-second timeout — if a pattern still manages to hang at runtime, the affected file receives a `Z009: ANALYSIS_TIMEOUT` finding instead of blocking your CI pipeline indefinitely. +**ReDoS Protection.** If you add custom regex patterns via `[[custom_rules]]` in `zenzic.toml`, Zenzic stress-tests each pattern with a 100 ms canary before it ever runs against your files. Patterns that exhibit catastrophic backtracking are rejected at startup with a clear error. As a second safety net, every worker process has a 30-second timeout — if a pattern still manages to hang at runtime, the affected file receives a `Z902: RULE_TIMEOUT` finding instead of blocking your CI pipeline indefinitely. ### Circular links diff --git a/docs/reference/finding-codes.mdx b/docs/reference/finding-codes.mdx index a8616ec..af86838 100644 --- a/docs/reference/finding-codes.mdx +++ b/docs/reference/finding-codes.mdx @@ -662,6 +662,24 @@ Z906 is an informational diagnostic. It does not fail the workflow step and is s --- +### Z907: I18N_PARITY {#z907} + +:::info[Quality Score — Not included] +Z907 is a **bilingual integrity check**. It does not reduce the [Deterministic Quality Score](../explanation/health-metrics.mdx). Resolve it to ensure your translated content is complete and consistent. +::: + +* **Severity:** `warning` +* **Technical Context:** Emitted by the I18n Parity module when the translation mirror of a base-language documentation file is missing, or when the frontmatter of a translated file diverges from the canonical base-language version. Two specific invariants are enforced: + 1. **Mirror presence:** Every `.md` / `.mdx` file in the base `docs/` tree must have a counterpart in every configured `i18n//` directory. A missing mirror means a locale serves the untranslated fallback silently. + 2. **Frontmatter parity:** The translated file’s frontmatter (at minimum `sidebar_position`, `sidebar_label`, `title`) must be structurally consistent with the base file. A stale or missing key means the locale sidebar renders incorrectly. +* **Remediation Steps:** + 1. Create the missing translation file at the corresponding path under `i18n//docusaurus-plugin-content-docs/current/`. + 2. Copy the base-language frontmatter block and translate the values — do not add or remove keys relative to the base. + 3. Run `zenzic check all` again to confirm parity is restored. + 4. For intentional asymmetry (e.g. a locale-only page or a draft not yet translated), suppress with `{/* zenzic:ignore Z907 */}` on the frontmatter block or add the file pattern to `i18n_exclude_patterns` in `zenzic.toml`. + +--- + ### Suppressing Diagnostics Zenzic supports **line-level, per-code suppression** via inline comments. Add a `zenzic:ignore` comment at the end of any line to silence a specific diagnostic for that line only. @@ -702,30 +720,7 @@ Suppression is for intentional, documented decisions — not for silencing findi --- -## Legacy Codes \[Deprecated\] {#legacy-codes} - -The following codes appeared in Zenzic output prior to **v0.6.0**. They are formally -**deprecated** and are never emitted by current Zenzic output. Zenzic's internal `normalize()` -function silently maps them to their canonical equivalents so that legacy CI log parsers continue -to work during the transition period. - -| Legacy Code | Status | Canonical Replacement | Context | -| :---: | :---: | :--- | :--- | -| `Z001` | **\[DEPRECATED\]** | [`Z101` LINK\_BROKEN](#z101) | Emitted by `VSMBrokenLinkRule` pre-v0.6.0 | -| `Z002` | **\[DEPRECATED\]** | [`Z103` ORPHAN\_LINK](#z103) | Emitted by `VSMBrokenLinkRule` pre-v0.6.0 | -| `Z009` | **\[DEPRECATED\]** | [`Z902` RULE\_TIMEOUT](#z902) | Emitted by the rule engine pre-v0.6.0 | - -:::note[Z000 — Fatal configuration guard, not a finding] -`Z000` is **not a finding code** emitted during analysis. It is a fatal configuration guard -raised as a `ConfigurationError` *before* any analysis begins when an unsupported engine name is -detected (for example, the permanently removed `"vanilla"` engine). It has no canonical finding -replacement and will never appear in a SARIF or JSON report. -::: - -If you encounter `Z001`, `Z002`, or `Z009` in your CI logs, update your Zenzic installation -to **v0.7.0 (Quartz Maturity) or later**. These legacy codes will be removed entirely in the next major version. - -### Integration with CI/CD +## Integration with CI/CD {#cicd-integration} For maximum effectiveness, integrate Zenzic checks into your CI/CD pipeline: diff --git a/i18n/it/docusaurus-plugin-content-docs/current/reference/finding-codes.mdx b/i18n/it/docusaurus-plugin-content-docs/current/reference/finding-codes.mdx index d1d6c7d..8716114 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/reference/finding-codes.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/reference/finding-codes.mdx @@ -664,6 +664,24 @@ Z906 è un diagnostic informativo. Non fa fallire lo step del workflow ed è sop --- +### Z907: I18N_PARITY {#z907} + +:::info[Non incluso nel Quality Score] +Z907 è un **controllo di integrità bilingue**. Non riduce il [Punteggio di Qualità Deterministico](../explanation/health-metrics.mdx). Risolvilo per garantire che i tuoi contenuti tradotti siano completi e coerenti. +::: + +* **Gravità:** `warning` +* **Contesto Tecnico:** Emesso dal modulo di Parità I18n quando manca il mirror di traduzione di un file di documentazione nella lingua base, o quando il frontmatter di un file tradotto diverge dalla versione canonica nella lingua base. Vengono applicati due invarianti specifici: + 1. **Presenza del mirror:** Ogni file `.md` / `.mdx` nell’albero `docs/` base deve avere un corrispettivo in ogni directory `i18n//` configurata. Un mirror mancante significa che una locale serve silenziosamente il fallback non tradotto. + 2. **Parità frontmatter:** Il frontmatter del file tradotto (almeno `sidebar_position`, `sidebar_label`, `title`) deve essere strutturalmente coerente con il file base. Una chiave obsoleta o mancante causa un rendering errato della sidebar locale. +* **Passi di Rimedio:** + 1. Crea il file di traduzione mancante nel percorso corrispondente sotto `i18n//docusaurus-plugin-content-docs/current/`. + 2. Copia il blocco frontmatter della lingua base e traduci i valori — non aggiungere né rimuovere chiavi rispetto alla base. + 3. Esegui nuovamente `zenzic check all` per confermare che la parità è ripristinata. + 4. Per asimmetrie intenzionali (es. una pagina specifica per la locale o una bozza non ancora tradotta), sopprimi con `{/* zenzic:ignore Z907 */}` sul blocco frontmatter o aggiungi il pattern del file a `i18n_exclude_patterns` in `zenzic.toml`. + +--- + ## Best Practices & Configurazione Avanzata ### Soppressione Diagnostiche @@ -706,31 +724,7 @@ La soppressione è per decisioni intenzionali e documentate — non per silenzia --- -## Codici Legacy \[Deprecati\] {#legacy-codes} - -I seguenti codici apparivano nell'output di Zenzic prima della versione **v0.6.0**. Sono -formalmente **deprecati** e non vengono mai emessi dall'output corrente di Zenzic. La funzione -interna `normalize()` li mappa silenziosamente ai loro equivalenti canonici, garantendo la -compatibilità con i log CI legacy durante il periodo di transizione. - -| Codice Legacy | Stato | Sostituzione Canonica | Contesto | -| :---: | :---: | :--- | :--- | -| `Z001` | **\[DEPRECATO\]** | [`Z101` LINK\_BROKEN](#z101) | Emesso da `VSMBrokenLinkRule` pre-v0.6.0 | -| `Z002` | **\[DEPRECATO\]** | [`Z103` ORPHAN\_LINK](#z103) | Emesso da `VSMBrokenLinkRule` pre-v0.6.0 | -| `Z009` | **\[DEPRECATO\]** | [`Z902` RULE\_TIMEOUT](#z902) | Emesso dal motore delle regole pre-v0.6.0 | - -:::note[Z000 — Guardia di configurazione fatale, non un finding] -`Z000` **non è un codice di finding** emesso durante l'analisi. È una guardia di configurazione -fatale sollevata come `ConfigurationError` *prima* che l'analisi abbia inizio, quando viene -rilevato un nome di engine non supportato (ad esempio, il motore `"vanilla"` rimosso in modo -permanente). Non ha alcun finding sostitutivo canonico e non apparirà mai in un report SARIF -o JSON. -::: - -Se incontri `Z001`, `Z002` o `Z009` nei log CI, aggiorna Zenzic alla versione **v0.7.0 (Quartz Maturity) o -superiore**. Questi codici legacy verranno rimossi completamente nella prossima versione maggiore. - -### Integrazione con CI/CD +## Integrazione con CI/CD {#cicd-integration} Per massima efficacia, integra i check Zenzic nella tua pipeline CI/CD: diff --git a/justfile b/justfile index f9f760c..349cc09 100644 --- a/justfile +++ b/justfile @@ -50,8 +50,8 @@ preview: build lint *args: uvx pre-commit run {{args}} -# Recommended final local check (4-Gates Standard: pre-commit + typecheck + build + codes parity) -verify: _check-hooks lint-all typecheck build verify-codes +# Recommended final local check (4-Gates Standard: pre-commit + build + codes parity) +verify: _check-hooks lint-all build verify-codes # Verify Zxxx code parity between codes.py and finding-codes.mdx (EN + IT) verify-codes: @@ -62,7 +62,7 @@ verify-codes: lint-all: uvx pre-commit run --all-files -build: check +build: npm run build check *args: @@ -73,7 +73,7 @@ check *args: --exclude-url "https://www.contributor-covenant.org/version/2/1/code_of_conduct.html" ) CORE_PATH="${ZENZIC_PROJECT_PATH:-../zenzic}" - + if [ -d "$CORE_PATH" ]; then echo "🛡️ [Zenzic Sentinel] Local core detected. Using: $CORE_PATH" uv run --project "$CORE_PATH" zenzic check all --strict "${GUARD[@]}" {{args}} @@ -104,6 +104,8 @@ doctor: _check-hooks: #!/usr/bin/env bash if [ ! -f .git/hooks/pre-push ]; then - echo "⚠️ WARNING: Pre-push hook not installed — commits are unprotected before push." - echo "👉 Run: pre-commit install -t pre-push" - fi \ No newline at end of file + echo -e "\033[33m⚠️ WARNING: Pre-push hook is not installed.\033[0m" + echo "Without it, you might accidentally push broken code to GitHub and fail the remote CI." + echo "👉 Fix it by running: uvx pre-commit install -t pre-push" + echo "" + fi From c88b0b9642c41c279491200ca0b97c7d63c64a53 Mon Sep 17 00:00:00 2001 From: PythonWoods Date: Fri, 8 May 2026 18:38:52 +0200 Subject: [PATCH 06/18] chore: replace bash bump script with bump-my-version config and just release recipe --- .bumpversion.toml | 87 ++++++++ justfile | 20 +- scripts/bump-version.sh | 214 ------------------- static/assets/brand/zenzic-brand-system.html | 12 +- 4 files changed, 111 insertions(+), 222 deletions(-) create mode 100644 .bumpversion.toml delete mode 100755 scripts/bump-version.sh diff --git a/.bumpversion.toml b/.bumpversion.toml new file mode 100644 index 0000000..c0bbcb2 --- /dev/null +++ b/.bumpversion.toml @@ -0,0 +1,87 @@ +[tool.bumpversion] +current_version = "0.7.0" +parse = "(?P\\d+)\\.(?P\\d+)\\.(?P\\d+)" +serialize = ["{major}.{minor}.{patch}"] + +[[tool.bumpversion.files]] +filename = "package.json" +search = '"name": "zenzic-temp-docs",\n "version": "\\d+\\.\\d+\\.\\d+",' +replace = '"name": "zenzic-temp-docs",\n "version": "{new_version}",' +regex = true + +[[tool.bumpversion.files]] +filename = "package-lock.json" +search = '"name": "zenzic-temp-docs",\n "version": "\\d+\\.\\d+\\.\\d+",' +replace = '"name": "zenzic-temp-docs",\n "version": "{new_version}",' +regex = true + +[[tool.bumpversion.files]] +filename = "package-lock.json" +search = '"": {\n "name": "zenzic-temp-docs",\n "version": "\\d+\\.\\d+\\.\\d+",' +replace = '"": {\n "name": "zenzic-temp-docs",\n "version": "{new_version}",' +regex = true + +[[tool.bumpversion.files]] +filename = "docusaurus.config.ts" +search = "'{current_version}'" +replace = "'{new_version}'" + +[[tool.bumpversion.files]] +filename = "docusaurus.config.ts" +search = "v{current_version}" +replace = "v{new_version}" + +[[tool.bumpversion.files]] +filename = "README.md" +search = "v{current_version}" +replace = "v{new_version}" + +[[tool.bumpversion.files]] +filename = "README.it.md" +search = "v{current_version}" +replace = "v{new_version}" + +[[tool.bumpversion.files]] +filename = "RELEASE.md" +search = "v{current_version}" +replace = "v{new_version}" + +[[tool.bumpversion.files]] +filename = "RELEASE.it.md" +search = "v{current_version}" +replace = "v{new_version}" + +[[tool.bumpversion.files]] +filename = "i18n/en/code.json" +search = "v{current_version}" +replace = "v{new_version}" + +[[tool.bumpversion.files]] +filename = "i18n/it/code.json" +search = "v{current_version}" +replace = "v{new_version}" + +[[tool.bumpversion.files]] +filename = "src/components/Homepage/Hero.tsx" +search = "v{current_version}" +replace = "v{new_version}" + +[[tool.bumpversion.files]] +filename = "src/components/Homepage/Quickstart.tsx" +search = "zenzic {current_version}" +replace = "zenzic {new_version}" + +[[tool.bumpversion.files]] +filename = "src/pages/index.tsx" +search = '"softwareVersion": "{current_version}"' +replace = '"softwareVersion": "{new_version}"' + +[[tool.bumpversion.files]] +filename = "docs/how-to/configure-ci-cd.mdx" +search = 'version: "{current_version}"' +replace = 'version: "{new_version}"' + +[[tool.bumpversion.files]] +filename = "i18n/it/docusaurus-plugin-content-docs/current/how-to/configure-ci-cd.mdx" +search = 'version: "{current_version}"' +replace = 'version: "{new_version}"' diff --git a/justfile b/justfile index 349cc09..d4a3db2 100644 --- a/justfile +++ b/justfile @@ -93,8 +93,24 @@ markdownlint: reuse: uvx reuse lint -bump version badge='': - @bash scripts/bump-version.sh "{{version}}" "{{badge}}" +# Release orchestration: explicit, transparent, and lockfile-first. +release part: + #!/usr/bin/env bash + set -euo pipefail + case "{{ part }}" in + patch|minor|major) ;; + *) echo "Invalid part '{{ part }}'. Use patch|minor|major"; exit 2 ;; + esac + uvx --from "bump-my-version==1.2.6" bump-my-version bump {{ part }} + npm ci + version="$(uvx --from "bump-my-version==1.2.6" bump-my-version show current_version)" + if git rev-parse "v${version}" >/dev/null 2>&1; then + echo "Tag v${version} already exists. Aborting." + exit 3 + fi + git add -u + git commit -m "release: bump version to ${version}" + git tag -a "v${version}" -m "Release v${version}" doctor: @node -v || echo "node missing" diff --git a/scripts/bump-version.sh b/scripts/bump-version.sh deleted file mode 100755 index 9c160a0..0000000 --- a/scripts/bump-version.sh +++ /dev/null @@ -1,214 +0,0 @@ -#!/usr/bin/env bash -# SPDX-FileCopyrightText: 2026 PythonWoods -# SPDX-License-Identifier: Apache-2.0 - -# bump-version.sh — Update all hardcoded Zenzic version references in zenzic-doc. -# -# Usage: -# bash scripts/bump-version.sh NEW_VERSION [NEW_BADGE] -# -# NEW_BADGE: full hero badge text. -# Defaults to: v{NEW_VERSION} Stable -# -# Example (with codename): -# bash scripts/bump-version.sh 0.6.3 'v0.6.3 "Quartz Flux" Stable' -# -# Example (generic stable): -# bash scripts/bump-version.sh 0.6.3 - -set -euo pipefail - -cd "$(dirname "$0")/.." - -NEW="${1:?Usage: $0 NEW_VERSION [NEW_BADGE]}" -export BUMP_NEW="${NEW}" -export BUMP_NEW_BADGE="${2:-v${NEW} Stable}" - -# Detect current version from the canonical source (docusaurus.config.ts footer). -BUMP_OLD=$(grep -oP 'Zenzic v\K[0-9]+\.[0-9]+\.[0-9]+' docusaurus.config.ts | head -1) -export BUMP_OLD - -echo "Bumping: v${BUMP_OLD} → v${BUMP_NEW}" -echo "Badge: ${BUMP_NEW_BADGE}" -echo "" - -python3 - <<'PYEOF' -import os, json -from pathlib import Path - -old = os.environ['BUMP_OLD'] -new = os.environ['BUMP_NEW'] -new_badge = os.environ['BUMP_NEW_BADGE'] - -# Read current badge text from canonical EN source. -code_en = Path('i18n/en/code.json') -data_en = json.loads(code_en.read_text()) -old_badge = data_en['homepage.hero.badge']['message'] - -changes = 0 - -def replace_file(path_str, old_str, new_str): - global changes - p = Path(path_str) - content = p.read_text() - if old_str not in content: - print(f" ⚠ {path_str}: pattern not found, skipping") - return - p.write_text(content.replace(old_str, new_str)) - changes += 1 - print(f" ✓ {path_str}") - -# 1a. docusaurus.config.ts — footer copyright line -replace_file('docusaurus.config.ts', f'Zenzic v{old}', f'Zenzic v{new}') - -# 1b. docusaurus.config.ts — navbar version badge (HTML span) -replace_file('docusaurus.config.ts', f'>v{old}<', f'>v{new}<') - -# 2. Quickstart.tsx — terminal "ready" prompt -replace_file('src/components/Homepage/Quickstart.tsx', f'zenzic {old}', f'zenzic {new}') - -# 3. pages/index.tsx — JSON-LD softwareVersion -replace_file('src/pages/index.tsx', f'"softwareVersion": "{old}"', f'"softwareVersion": "{new}"') - -# 4. Hero.tsx — default badge text inside fallback -replace_file('src/components/Homepage/Hero.tsx', old_badge, new_badge) - -# 5. i18n/en/code.json — EN hero badge message -data_en['homepage.hero.badge']['message'] = new_badge -code_en.write_text(json.dumps(data_en, indent=2, ensure_ascii=False) + '\n') -changes += 1 -print(f" ✓ i18n/en/code.json") - -# 6. i18n/it/code.json — IT hero badge message (mirrors EN badge for version tag) -code_it = Path('i18n/it/code.json') -data_it = json.loads(code_it.read_text()) -data_it['homepage.hero.badge']['message'] = new_badge -code_it.write_text(json.dumps(data_it, indent=2, ensure_ascii=False) + '\n') -changes += 1 -print(f" ✓ i18n/it/code.json") - -# 7. static/assets/brand/zenzic-brand-system.html — version + codename -import re as _re -brand_html = Path('static/assets/brand/zenzic-brand-system.html') -brand_content = brand_html.read_text() -brand_changed = False - -# 7a. Version string: replace every occurrence of v{old} → v{new} -if f'v{old}' in brand_content: - brand_content = brand_content.replace(f'v{old}', f'v{new}') - brand_changed = True - -# 7b. Codename: extract from badge strings (format: v1.2.3 "Codename" Stable) -# Replace in all three case variants used in the HTML: -# Title Case → Quartz Maturity -# ALL CAPS → OBSIDIAN MATURITY -# all lower → obsidian maturity -m_old = _re.search(r'"([^"]+)"', old_badge) -m_new = _re.search(r'"([^"]+)"', new_badge) -if m_old and m_new: - old_code = m_old.group(1) # e.g. "Quartz Maturity" - new_code = m_new.group(1) # e.g. "Quantum Glass" - if old_code != new_code: - for variant in ( - (old_code, new_code), - (old_code.upper(), new_code.upper()), - (old_code.lower(), new_code.lower()), - ): - if variant[0] in brand_content: - brand_content = brand_content.replace(*variant) - brand_changed = True - -if brand_changed: - brand_html.write_text(brand_content) - changes += 1 - print(f" ✓ static/assets/brand/zenzic-brand-system.html") -else: - print(f" ⚠ static/assets/brand/zenzic-brand-system.html: nothing to update, skipping") - -# 8. Social card SVGs — version text (both dark and light variants) -for svg_path in ('static/assets/social/social-card.svg', - 'static/assets/social/social-card-light.svg'): - replace_file(svg_path, f'v{old}', f'v{new}') - if m_old and m_new and old_code != new_code: - # Also update codename in ALL CAPS (used in SVG text elements) - p = Path(svg_path) - c = p.read_text() - upper_old = old_code.upper() - upper_new = new_code.upper() - if upper_old in c: - p.write_text(c.replace(upper_old, upper_new)) - changes += 1 - print(f" ✓ {svg_path} (codename ALL-CAPS)") - -# 9. README.md + RELEASE.md — header badge + alignment notice -replace_file('README.md', f'Zenzic_Core-v{old}', f'Zenzic_Core-v{new}') -replace_file('README.md', f'Zenzic v{old}', f'Zenzic v{new}') -replace_file('README.md', f'v{old}', f'v{new}') # bare v{old} (e.g. "Discovered in: v{old}") -replace_file('RELEASE.md', f'v{old}', f'v{new}') -if m_old and m_new and old_code != new_code: - for target in ('README.md', 'RELEASE.md'): - p = Path(target) - c = p.read_text() - if old_code in c: - p.write_text(c.replace(old_code, new_code)) - changes += 1 - print(f" ✓ {target} (codename)") - -# 10. Regenerate ALL brand PNGs from their canonical SVGs (pure cairosvg — no subprocess). -# Then rebuild brand-kit.zip using Python zipfile (no Node subprocess). -# -# MANIFEST: (svg_source, png_target, width, height) -# - static/assets/brand/svg/ is the canonical SVG source (also packed verbatim in brand-kit.zip) -# - static/assets/brand/png/ is the canonical PNG target (packed in brand-kit.zip) -# - static/assets/social/ sources are handled separately -BRAND_PNG_MANIFEST = [ - # (svg_path, png_path, width, height) - ('static/assets/brand/svg/zenzic-icon.svg', - 'static/assets/brand/png/zenzic-icon-512.png', 512, 512), - ('static/assets/brand/svg/zenzic-nav-dark.svg', - 'static/assets/brand/png/zenzic-nav-dark.png', 640, 180), - ('static/assets/brand/svg/zenzic-nav-light.svg', - 'static/assets/brand/png/zenzic-nav-light.png', 640, 180), - ('static/assets/brand/svg/zenzic-wordmark.svg', - 'static/assets/brand/png/zenzic-wordmark.png', 600, 120), - ('static/assets/social/social-card.svg', - 'static/assets/social/social-card.png', 1200, 630), - ('static/assets/social/social-card-light.svg', - 'static/assets/social/social-card-light.png', 1200, 630), -] - -print("\nRegenerating brand PNGs via cairosvg (pure Python — no subprocess) …") -try: - import cairosvg as _svg - - for svg_src, png_dst, w, h in BRAND_PNG_MANIFEST: - _svg.svg2png(url=svg_src, write_to=png_dst, output_width=w, output_height=h) - changes += 1 - print(f" ✓ {png_dst} [{w}×{h}]") - - # 11. Rebuild brand-kit.zip using Python zipfile (no Node subprocess). - # Mirrors the logic in scripts/build-assets.js. - import zipfile as _zip - ZIP_SOURCES = [ - ('static/assets/brand', 'brand'), - ('static/assets/social', 'social'), - ] - zip_out = Path('static/assets/brand/brand-kit.zip') - with _zip.ZipFile(zip_out, 'w', compression=_zip.ZIP_DEFLATED) as zf: - for src_dir, prefix in ZIP_SOURCES: - src = Path(src_dir) - if not src.exists(): - continue - for f in sorted(src.rglob('*')): - if f.is_file() and f != zip_out: - arcname = f'{prefix}/{f.relative_to(src)}' - zf.write(f, arcname) - changes += 1 - print(f"\n ✓ static/assets/brand/brand-kit.zip (rebuilt — {zip_out.stat().st_size // 1024} KB)") - -except ImportError: - print(" ⚠ cairosvg not installed — PNGs and brand-kit.zip NOT regenerated.") - print(" Install: pip install cairosvg") - -print(f"\n✓ Bump complete ({changes} file(s) updated). Run 'just verify' to validate.") -PYEOF diff --git a/static/assets/brand/zenzic-brand-system.html b/static/assets/brand/zenzic-brand-system.html index 807baea..2fb25ff 100644 --- a/static/assets/brand/zenzic-brand-system.html +++ b/static/assets/brand/zenzic-brand-system.html @@ -3,7 +3,7 @@ - Zenzic · Brand System · v0.7.0 · Obsidian Maturity + Zenzic · Brand System · v0.7.1a1 · Obsidian Maturity @@ -155,7 +155,7 @@ -

Zenzic · Brand System · v0.7.0 · Obsidian Maturity

+

Zenzic · Brand System · v0.7.1a1 · Obsidian Maturity

Zenzic THE SAFE HARBOR FOR MARKDOWN DOCUMENTATION - v0.7.0 · OBSIDIAN MATURITY + v0.7.1a1 · OBSIDIAN MATURITY @@ -451,7 +451,7 @@
Sentinel Palette -

Palette v0.7.0 — Obsidian Maturity Edition  ·  Bimodal Indigo: Light #4338ca (AAA 7.4:1) · Dark #a5b4fc (AAA 8.9:1)

+

Palette v0.7.1a1 — Obsidian Maturity Edition  ·  Bimodal Indigo: Light #4338ca (AAA 7.4:1) · Dark #a5b4fc (AAA 8.9:1)

Identity

@@ -541,7 +541,7 @@

Code / UI · JetBrains Mono

-

SENTINEL · SHIELD · HARBOR
uvx zenzic check all ./docs
v0.7.0 · obsidian maturity · exit 0

+

SENTINEL · SHIELD · HARBOR
uvx zenzic check all ./docs
v0.7.1a1 · obsidian maturity · exit 0

@@ -703,7 +703,7 @@

CLI Output — Color Mapping

- ▮ ZENZIC SENTINEL v0.7.0
+ ▮ ZENZIC SENTINEL v0.7.1a1
✨ Obsidian Seal: All checks passed.
⚠ WARNING docs/guide.md:14
✗ ERROR docs/api.md:88
From db6de357fe1cfc9986577e85ca5a77fd2b7ae1d4 Mon Sep 17 00:00:00 2001 From: PythonWoods Date: Fri, 8 May 2026 18:53:30 +0200 Subject: [PATCH 07/18] feat(release): add version display and dry-run release bump functionality --- justfile | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/justfile b/justfile index d4a3db2..ea5eaf9 100644 --- a/justfile +++ b/justfile @@ -112,6 +112,15 @@ release part: git commit -m "release: bump version to ${version}" git tag -a "v${version}" -m "Release v${version}" +# Show the current project version +version: + @uvx --from "bump-my-version==1.2.6" bump-my-version show current_version + +# Simulate a release bump without modifying any files +# Usage: just release-dry patch|minor|major +release-dry part: + uvx --from "bump-my-version==1.2.6" bump-my-version bump {{part}} --dry-run --verbose + doctor: @node -v || echo "node missing" @npm -v || echo "npm missing" From 9e1eb00cd7975f1ffb8816be6f4e3c776ecb6fa1 Mon Sep 17 00:00:00 2001 From: PythonWoods Date: Fri, 8 May 2026 19:03:17 +0200 Subject: [PATCH 08/18] fix: update package name from zenzic-temp-docs to zenzic-docs in package.json and package-lock.json --- package-lock.json | 4 ++-- package.json | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/package-lock.json b/package-lock.json index 30c4b65..198995f 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,11 +1,11 @@ { - "name": "zenzic-temp-docs", + "name": "zenzic-docs", "version": "0.0.0", "lockfileVersion": 3, "requires": true, "packages": { "": { - "name": "zenzic-temp-docs", + "name": "zenzic-docs", "version": "0.0.0", "dependencies": { "@docusaurus/core": "3.10.1", diff --git a/package.json b/package.json index 412a8ee..e54c26f 100644 --- a/package.json +++ b/package.json @@ -1,5 +1,5 @@ { - "name": "zenzic-temp-docs", + "name": "zenzic-docs", "version": "0.0.0", "private": true, "scripts": { From 7ef56e4fcc53029fa034e9bd092cf6c207e06fc8 Mon Sep 17 00:00:00 2001 From: PythonWoods Date: Fri, 8 May 2026 19:05:38 +0200 Subject: [PATCH 09/18] fix: update package name from zenzic-temp-docs to zenzic-docs in .bumpversion.toml --- .bumpversion.toml | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/.bumpversion.toml b/.bumpversion.toml index c0bbcb2..e74f328 100644 --- a/.bumpversion.toml +++ b/.bumpversion.toml @@ -5,20 +5,20 @@ serialize = ["{major}.{minor}.{patch}"] [[tool.bumpversion.files]] filename = "package.json" -search = '"name": "zenzic-temp-docs",\n "version": "\\d+\\.\\d+\\.\\d+",' -replace = '"name": "zenzic-temp-docs",\n "version": "{new_version}",' +search = '"name": "zenzic-docs",\n "version": "\\d+\\.\\d+\\.\\d+",' +replace = '"name": "zenzic-docs",\n "version": "{new_version}",' regex = true [[tool.bumpversion.files]] filename = "package-lock.json" -search = '"name": "zenzic-temp-docs",\n "version": "\\d+\\.\\d+\\.\\d+",' -replace = '"name": "zenzic-temp-docs",\n "version": "{new_version}",' +search = '"name": "zenzic-docs",\n "version": "\\d+\\.\\d+\\.\\d+",' +replace = '"name": "zenzic-docs",\n "version": "{new_version}",' regex = true [[tool.bumpversion.files]] filename = "package-lock.json" -search = '"": {\n "name": "zenzic-temp-docs",\n "version": "\\d+\\.\\d+\\.\\d+",' -replace = '"": {\n "name": "zenzic-temp-docs",\n "version": "{new_version}",' +search = '"": {\n "name": "zenzic-docs",\n "version": "\\d+\\.\\d+\\.\\d+",' +replace = '"": {\n "name": "zenzic-docs",\n "version": "{new_version}",' regex = true [[tool.bumpversion.files]] From 85e5359e5bbe1aef19cf0665573cce3eee468b67 Mon Sep 17 00:00:00 2001 From: PythonWoods Date: Fri, 8 May 2026 19:09:42 +0200 Subject: [PATCH 10/18] fix: update package name from zenzic-docs to zenzic-doc in .bumpversion.toml and package.json --- .bumpversion.toml | 29 ++++++++++++++++++++--------- package.json | 2 +- 2 files changed, 21 insertions(+), 10 deletions(-) diff --git a/.bumpversion.toml b/.bumpversion.toml index e74f328..c73be53 100644 --- a/.bumpversion.toml +++ b/.bumpversion.toml @@ -5,21 +5,32 @@ serialize = ["{major}.{minor}.{patch}"] [[tool.bumpversion.files]] filename = "package.json" -search = '"name": "zenzic-docs",\n "version": "\\d+\\.\\d+\\.\\d+",' -replace = '"name": "zenzic-docs",\n "version": "{new_version}",' -regex = true +search = ''' + "name": "zenzic-doc", + "version": "{current_version}",''' +replace = ''' + "name": "zenzic-doc", + "version": "{new_version}",''' [[tool.bumpversion.files]] filename = "package-lock.json" -search = '"name": "zenzic-docs",\n "version": "\\d+\\.\\d+\\.\\d+",' -replace = '"name": "zenzic-docs",\n "version": "{new_version}",' -regex = true +search = ''' + "name": "zenzic-doc", + "version": "{current_version}",''' +replace = ''' + "name": "zenzic-doc", + "version": "{new_version}",''' [[tool.bumpversion.files]] filename = "package-lock.json" -search = '"": {\n "name": "zenzic-docs",\n "version": "\\d+\\.\\d+\\.\\d+",' -replace = '"": {\n "name": "zenzic-docs",\n "version": "{new_version}",' -regex = true +search = ''' + "": { + "name": "zenzic-doc", + "version": "{current_version}",''' +replace = ''' + "": { + "name": "zenzic-doc", + "version": "{new_version}",''' [[tool.bumpversion.files]] filename = "docusaurus.config.ts" diff --git a/package.json b/package.json index e54c26f..20e1233 100644 --- a/package.json +++ b/package.json @@ -1,5 +1,5 @@ { - "name": "zenzic-docs", + "name": "zenzic-doc", "version": "0.0.0", "private": true, "scripts": { From fb5a80fe7e87bf998f7aa0213727a76b4dffcda3 Mon Sep 17 00:00:00 2001 From: PythonWoods Date: Fri, 8 May 2026 19:11:43 +0200 Subject: [PATCH 11/18] fix: update package.json and package-lock.json versioning to use new version format --- .bumpversion.toml | 26 ++++++++++++-------------- 1 file changed, 12 insertions(+), 14 deletions(-) diff --git a/.bumpversion.toml b/.bumpversion.toml index c73be53..82f7bfd 100644 --- a/.bumpversion.toml +++ b/.bumpversion.toml @@ -12,25 +12,23 @@ replace = ''' "name": "zenzic-doc", "version": "{new_version}",''' +[[tool.bumpversion.files]] +filename = "package.json" +search = '"name":\s*"zenzic-doc",\s*"version":\s*"{current_version}"' +replace = '"name": "zenzic-doc",\n "version": "{new_version}"' +regex = true + [[tool.bumpversion.files]] filename = "package-lock.json" -search = ''' - "name": "zenzic-doc", - "version": "{current_version}",''' -replace = ''' - "name": "zenzic-doc", - "version": "{new_version}",''' +search = '"name":\s*"zenzic-doc",\s*"version":\s*"{current_version}"' +replace = '"name": "zenzic-doc",\n "version": "{new_version}"' +regex = true [[tool.bumpversion.files]] filename = "package-lock.json" -search = ''' - "": { - "name": "zenzic-doc", - "version": "{current_version}",''' -replace = ''' - "": { - "name": "zenzic-doc", - "version": "{new_version}",''' +search = '"":\s*\{\s*"name":\s*"zenzic-doc",\s*"version":\s*"{current_version}"' +replace = '"": {\n "name": "zenzic-doc",\n "version": "{new_version}"' +regex = true [[tool.bumpversion.files]] filename = "docusaurus.config.ts" From 50611ff963c5420419eb4b09f74c90e2aae3ceb6 Mon Sep 17 00:00:00 2001 From: PythonWoods Date: Fri, 8 May 2026 19:13:56 +0200 Subject: [PATCH 12/18] fix: update package name references in .bumpversion.toml for consistency Co-authored-by: Copilot --- .bumpversion.toml | 19 +++++-------------- 1 file changed, 5 insertions(+), 14 deletions(-) diff --git a/.bumpversion.toml b/.bumpversion.toml index 82f7bfd..1bacc65 100644 --- a/.bumpversion.toml +++ b/.bumpversion.toml @@ -5,29 +5,20 @@ serialize = ["{major}.{minor}.{patch}"] [[tool.bumpversion.files]] filename = "package.json" -search = ''' - "name": "zenzic-doc", - "version": "{current_version}",''' -replace = ''' - "name": "zenzic-doc", - "version": "{new_version}",''' - -[[tool.bumpversion.files]] -filename = "package.json" -search = '"name":\s*"zenzic-doc",\s*"version":\s*"{current_version}"' +search = '"name":\s*"zenzic-doc",\s*"version":\s*"\d+\.\d+\.\d+"' replace = '"name": "zenzic-doc",\n "version": "{new_version}"' regex = true [[tool.bumpversion.files]] filename = "package-lock.json" -search = '"name":\s*"zenzic-doc",\s*"version":\s*"{current_version}"' -replace = '"name": "zenzic-doc",\n "version": "{new_version}"' +search = '"name":\s*"zenzic-docs",\s*"version":\s*"\d+\.\d+\.\d+"' +replace = '"name": "zenzic-docs",\n "version": "{new_version}"' regex = true [[tool.bumpversion.files]] filename = "package-lock.json" -search = '"":\s*\{\s*"name":\s*"zenzic-doc",\s*"version":\s*"{current_version}"' -replace = '"": {\n "name": "zenzic-doc",\n "version": "{new_version}"' +search = '"":\s*\{\s*"name":\s*"zenzic-docs",\s*"version":\s*"\d+\.\d+\.\d+"' +replace = '"": {\n "name": "zenzic-docs",\n "version": "{new_version}"' regex = true [[tool.bumpversion.files]] From 2de2818bbf93533a57945e1b7cb68f7dfa8cfa7f Mon Sep 17 00:00:00 2001 From: PythonWoods Date: Fri, 8 May 2026 19:26:19 +0200 Subject: [PATCH 13/18] fix: remove package-lock.json references from .bumpversion.toml and update release-dry command in justfile Co-authored-by: Copilot --- .bumpversion.toml | 6 ------ justfile | 2 +- 2 files changed, 1 insertion(+), 7 deletions(-) diff --git a/.bumpversion.toml b/.bumpversion.toml index 1bacc65..5e0baa1 100644 --- a/.bumpversion.toml +++ b/.bumpversion.toml @@ -15,12 +15,6 @@ search = '"name":\s*"zenzic-docs",\s*"version":\s*"\d+\.\d+\.\d+"' replace = '"name": "zenzic-docs",\n "version": "{new_version}"' regex = true -[[tool.bumpversion.files]] -filename = "package-lock.json" -search = '"":\s*\{\s*"name":\s*"zenzic-docs",\s*"version":\s*"\d+\.\d+\.\d+"' -replace = '"": {\n "name": "zenzic-docs",\n "version": "{new_version}"' -regex = true - [[tool.bumpversion.files]] filename = "docusaurus.config.ts" search = "'{current_version}'" diff --git a/justfile b/justfile index ea5eaf9..f1da5e3 100644 --- a/justfile +++ b/justfile @@ -119,7 +119,7 @@ version: # Simulate a release bump without modifying any files # Usage: just release-dry patch|minor|major release-dry part: - uvx --from "bump-my-version==1.2.6" bump-my-version bump {{part}} --dry-run --verbose + uvx --from "bump-my-version==1.2.6" bump-my-version bump {{part}} --dry-run --allow-dirty --verbose doctor: @node -v || echo "node missing" From 1941ec4bd083d33e9249444b17a75c5850bb95fb Mon Sep 17 00:00:00 2001 From: PythonWoods Date: Fri, 8 May 2026 19:27:05 +0200 Subject: [PATCH 14/18] release: bump version to 0.7.1 --- .bumpversion.toml | 2 +- README.it.md | 6 +++--- README.md | 6 +++--- RELEASE.it.md | 6 +++--- RELEASE.md | 18 +++++++++--------- docs/how-to/configure-ci-cd.mdx | 4 ++-- docusaurus.config.ts | 4 ++-- i18n/en/code.json | 2 +- i18n/it/code.json | 2 +- .../current/how-to/configure-ci-cd.mdx | 4 ++-- package-lock.json | 4 ++-- package.json | 2 +- src/components/Homepage/Hero.tsx | 2 +- src/components/Homepage/Quickstart.tsx | 2 +- src/pages/index.tsx | 2 +- 15 files changed, 33 insertions(+), 33 deletions(-) diff --git a/.bumpversion.toml b/.bumpversion.toml index 5e0baa1..aa5477a 100644 --- a/.bumpversion.toml +++ b/.bumpversion.toml @@ -1,5 +1,5 @@ [tool.bumpversion] -current_version = "0.7.0" +current_version = "0.7.1" parse = "(?P\\d+)\\.(?P\\d+)\\.(?P\\d+)" serialize = ["{major}.{minor}.{patch}"] diff --git a/README.it.md b/README.it.md index 42a1b7a..509d621 100644 --- a/README.it.md +++ b/README.it.md @@ -8,7 +8,7 @@ # Guida per Sviluppatori zenzic-doc -[![Zenzic Core](https://img.shields.io/badge/Zenzic_Core-v0.7.0-4f46e5)](https://github.com/PythonWoods/zenzic) +[![Zenzic Core](https://img.shields.io/badge/Zenzic_Core-v0.7.1-4f46e5)](https://github.com/PythonWoods/zenzic) [![Docs CI](https://github.com/PythonWoods/zenzic-doc/actions/workflows/ci.yml/badge.svg)](https://github.com/PythonWoods/zenzic-doc/actions/workflows/ci.yml) [![License](https://img.shields.io/badge/license-Apache--2.0-0d9488?style=flat-square)](LICENSE) [![REUSE status](https://api.reuse.software/badge/github.com/PythonWoods/zenzic-doc)](https://api.reuse.software/info/github.com/PythonWoods/zenzic-doc) @@ -16,7 +16,7 @@ [![4-Gates: Sentinel Seal](https://img.shields.io/badge/4--Gates-Sentinel%20Seal-10b981?style=flat-square)](https://zenzic.dev/it/developers/explanation/adr-vault) [![REUSE 3.x compliant](https://img.shields.io/badge/REUSE-3.x%20compliant-0d9488?style=flat-square)](https://reuse.software/) -> **Questa documentazione è strettamente allineata a Zenzic v0.7.0 "Quarzo".** +> **Questa documentazione è strettamente allineata a Zenzic v0.7.1 "Quarzo".** > Se la versione del core cambia, esegui `just bump NEW_VERSION` per mantenere > sincronizzati tutti i riferimenti. @@ -341,7 +341,7 @@ i18n: { }, ``` -**Scoperto in:** v0.7.0 release audit (D090 "Il Lockdown i18n"). +**Scoperto in:** v0.7.1 release audit (D090 "Il Lockdown i18n"). ## 11) Checklist Pull Request diff --git a/README.md b/README.md index 4176d4d..1359377 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ # zenzic-doc Developer Guide -[![Zenzic Core](https://img.shields.io/badge/Zenzic_Core-v0.7.0-4f46e5)](https://github.com/PythonWoods/zenzic) +[![Zenzic Core](https://img.shields.io/badge/Zenzic_Core-v0.7.1-4f46e5)](https://github.com/PythonWoods/zenzic) [![Docs CI](https://github.com/PythonWoods/zenzic-doc/actions/workflows/ci.yml/badge.svg)](https://github.com/PythonWoods/zenzic-doc/actions/workflows/ci.yml) [![License](https://img.shields.io/badge/license-Apache--2.0-0d9488?style=flat-square)](LICENSE) [![REUSE status](https://api.reuse.software/badge/github.com/PythonWoods/zenzic-doc)](https://api.reuse.software/info/github.com/PythonWoods/zenzic-doc) @@ -16,7 +16,7 @@ [![4-Gates: Sentinel Seal](https://img.shields.io/badge/4--Gates-Sentinel%20Seal-10b981?style=flat-square)](https://zenzic.dev/developers/explanation/adr-vault) [![REUSE 3.x compliant](https://img.shields.io/badge/REUSE-3.x%20compliant-0d9488?style=flat-square)](https://reuse.software/) -> **This documentation is strictly aligned to Zenzic v0.7.0 "Quartz Maturity".** +> **This documentation is strictly aligned to Zenzic v0.7.1 "Quartz Maturity".** > If the core version changes, run `just bump NEW_VERSION` to keep all references in sync. This repository contains the Docusaurus documentation website for Zenzic. @@ -333,7 +333,7 @@ i18n: { }, ``` -**Discovered in:** v0.7.0 release audit (D090 "The i18n Lockdown"). +**Discovered in:** v0.7.1 release audit (D090 "The i18n Lockdown"). ## 11) Pull Request Checklist diff --git a/RELEASE.it.md b/RELEASE.it.md index 02cfe38..968e8a8 100644 --- a/RELEASE.it.md +++ b/RELEASE.it.md @@ -1,10 +1,10 @@ -# 💎 Zenzic v0.7.0 — L'Era del Quarzo (Quartz Maturity) +# 💎 Zenzic v0.7.1 — L'Era del Quarzo (Quartz Maturity) Questa release segna la nascita del Sistema di Conoscenza Sovrano. Dopo l'Epurazione del Quarzo, Zenzic abbandona definitivamente ogni residuo sperimentale per diventare un'infrastruttura deterministica di grado industriale. -## 🏛️ I Pilastri della v0.7.0 +## 🏛️ I Pilastri della v0.7.1 - **Integrità Deterministica**: Assenza integrale di ogni dipendenza o logica probabilistica. Zenzic opera ora esclusivamente su fatti strutturali e invarianti certe. - **Sentinel Seal**: Un sistema di validazione a 4 stadi (4-Gates Standard) che garantisce la qualità assoluta prima di ogni push. @@ -13,7 +13,7 @@ Questa release segna la nascita del Sistema di Conoscenza Sovrano. Dopo l'Epuraz ## ⚠️ Nota di Evoluzione (Breaking Changes) -La v0.7.0 è l'Anno Zero. Le versioni precedenti sono ufficialmente deprecate poiché non seguono l'attuale architettura Diátaxis. Ogni riferimento ai vecchi brand o alle architetture legacy è stato rimosso per far posto a un ecosistema snello e focalizzato sulla purezza della sorgente. +La v0.7.1 è l'Anno Zero. Le versioni precedenti sono ufficialmente deprecate poiché non seguono l'attuale architettura Diátaxis. Ogni riferimento ai vecchi brand o alle architetture legacy è stato rimosso per far posto a un ecosistema snello e focalizzato sulla purezza della sorgente. ## 🚀 Verso il Futuro diff --git a/RELEASE.md b/RELEASE.md index c124e56..f0cda52 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -1,10 +1,10 @@ -# 💎 Zenzic v0.7.0 — The Quartz Era (Quartz Maturity) +# 💎 Zenzic v0.7.1 — The Quartz Era (Quartz Maturity) This release marks the birth of the Sovereign Knowledge System. Following the Quartz Purgation, Zenzic definitively abandons all experimental residues to become a deterministic, industrial-grade infrastructure. -## 🏛️ The Pillars of v0.7.0 +## 🏛️ The Pillars of v0.7.1 - **Deterministic Integrity**: Complete absence of any probabilistic dependency or logic. Zenzic now operates exclusively on structural facts and certain invariants. - **Sentinel Seal**: A 4-stage validation system (4-Gates Standard) ensuring absolute quality before every push. @@ -13,7 +13,7 @@ This release marks the birth of the Sovereign Knowledge System. Following the Qu ## ⚠️ Evolution Note (Breaking Changes) -v0.7.0 is Year Zero. Previous versions are officially deprecated as they do not follow the current Diátaxis architecture. Every reference to old brands or legacy architectures has been removed to make way for a lean ecosystem focused on source purity. +v0.7.1 is Year Zero. Previous versions are officially deprecated as they do not follow the current Diátaxis architecture. Every reference to old brands or legacy architectures has been removed to make way for a lean ecosystem focused on source purity. ## 🚀 Towards the Future @@ -48,7 +48,7 @@ The sidebar is autogenerated from the filesystem — no slug divergence permitte A blog (`/blog/`) has been inaugurated as the **Zenzic Blog**: the official engineering log of Zenzic. Six founding articles cover the v0.6.x sprint, the -AI-Driven Siege postmortem, and the v0.7.0 Quartz Maturity declaration. +AI-Driven Siege postmortem, and the v0.7.1 Quartz Maturity declaration. The blog inherits the full Quartz visual system: `#09090b` monolith surface, Zinc typography, Indigo author identity, Cyan accent. @@ -154,7 +154,7 @@ Changes: The Developer Area has been promoted from \`/docs/community/developers/*\` to its own top-level Docusaurus instance at \`/developers/*\`. The User Area remains at \`/docs/*\`. -| Before (v0.6.x) | After (v0.7.0) | +| Before (v0.6.x) | After (v0.7.1) | | :--- | :--- | | \`/docs/community/developers/*\` | \`/developers/*\` | | \`/docs/community/governance/*\` | \`/developers/governance/*\` | @@ -176,7 +176,7 @@ External bookmarks, blog posts, and search index entries must be updated. - **\`/developers/governance/technical-debt.mdx\`** (EN+IT) — first entry records **Z108 STALE_ALLOWLIST_ENTRY** as deferred to v0.8.0 with rationale. -> **EPOCH 7a.1 supersession (v0.7.0):** the `[link_validation].absolute_path_allowlist` +> **EPOCH 7a.1 supersession (v0.7.1):** the `[link_validation].absolute_path_allowlist` > mechanism above is **retired**. DocusaurusAdapter now auto-detects > multi-instance plugin URL prefixes Zero-Config — the `[link_validation]` block > has been deleted from `zenzic-doc/zenzic.toml`, the Z108 entry is closed by @@ -189,7 +189,7 @@ README of every Zenzic repository (zenzic, zenzic-doc, zenzic-action) --- -**v0.7.0 is the canonical stable portal for the Quartz Maturity sprint.** +**v0.7.1 is the canonical stable portal for the Quartz Maturity sprint.** | Gate | Result | |------|--------| @@ -212,7 +212,7 @@ convention: - **📜 Log** — terse patch-notes mirror of `RELEASE.md`, readable in ~30 seconds. -`📜 Log: v0.7.0 — Quartz Maturity` (`/blog/log-v070-quartz-maturity`) +`📜 Log: v0.7.1 — Quartz Maturity` (`/blog/log-v070-quartz-maturity`) fills the missing intermediate ring between Saga V and the raw release notes. @@ -256,6 +256,6 @@ across EN and IT in both tracks (`Z907 I18N_PARITY` clean). zenzic-doc is the documentation portal for Zenzic, developed by **PythonWoods**, based in Italy. The portal is the contract made visible. -**For the engine release notes, see [Zenzic Core v0.7.0](https://github.com/PythonWoods/zenzic/blob/main/RELEASE.md).** +**For the engine release notes, see [Zenzic Core v0.7.1](https://github.com/PythonWoods/zenzic/blob/main/RELEASE.md).** [**Visit the Portal →**](https://zenzic.dev) diff --git a/docs/how-to/configure-ci-cd.mdx b/docs/how-to/configure-ci-cd.mdx index abdc01d..290e462 100644 --- a/docs/how-to/configure-ci-cd.mdx +++ b/docs/how-to/configure-ci-cd.mdx @@ -201,7 +201,7 @@ jobs: uses: PythonWoods/zenzic-action@v1 with: - version: "0.7.0" # pin to a stable release + version: "0.7.1" # pin to a stable release format: sarif # emit SARIF for Code Scanning upload-sarif: "true" fail-on-error: "true" @@ -246,7 +246,7 @@ Slack notifications without re-parsing the SARIF file: id: zenzic uses: PythonWoods/zenzic-action@v1 with: - version: "0.7.0" + version: "0.7.1" - name: Post finding count diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 942b423..b5ad961 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -75,7 +75,7 @@ const config: Config = { lastVersion: 'current', versions: { current: { - label: '0.7.0', + label: '0.7.1', badge: false, banner: 'none', }, @@ -208,7 +208,7 @@ const config: Config = { footer: { style: 'dark', links: [], - copyright: `© ${new Date().getFullYear()} PythonWoods. Zenzic v0.7.0. Apache-2.0 License. · Python 3.11+ · Zero runtime dependencies`, + copyright: `© ${new Date().getFullYear()} PythonWoods. Zenzic v0.7.1. Apache-2.0 License. · Python 3.11+ · Zero runtime dependencies`, }, prism: { theme: prismThemes.github, diff --git a/i18n/en/code.json b/i18n/en/code.json index 63229d2..b0d713e 100644 --- a/i18n/en/code.json +++ b/i18n/en/code.json @@ -89,7 +89,7 @@ "message": "Scans every URL for leaked credentials - API keys, tokens. Exits with code 2 immediately." }, "homepage.hero.badge": { - "message": "v0.7.0 \"Quartz Maturity\" Stable", + "message": "v0.7.1 \"Quartz Maturity\" Stable", "description": "Wait release version badge" }, "homepage.hero.title": { diff --git a/i18n/it/code.json b/i18n/it/code.json index f4988a2..5cb1719 100644 --- a/i18n/it/code.json +++ b/i18n/it/code.json @@ -680,7 +680,7 @@ "message": "Scans every URL for leaked credentials - API keys, tokens. Exits with code 2 immediately." }, "homepage.hero.badge": { - "message": "v0.7.0 \"Quartz Maturity\" Stable", + "message": "v0.7.1 \"Quartz Maturity\" Stable", "description": "Wait release version badge" }, "homepage.hero.title": { diff --git a/i18n/it/docusaurus-plugin-content-docs/current/how-to/configure-ci-cd.mdx b/i18n/it/docusaurus-plugin-content-docs/current/how-to/configure-ci-cd.mdx index c7d8c64..e6955a2 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/how-to/configure-ci-cd.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/how-to/configure-ci-cd.mdx @@ -202,7 +202,7 @@ jobs: uses: PythonWoods/zenzic-action@v1 with: - version: "0.7.0" # fissa a una release stabile + version: "0.7.1" # fissa a una release stabile format: sarif # emetti SARIF per Code Scanning upload-sarif: "true" fail-on-error: "true" @@ -247,7 +247,7 @@ o notifiche Slack senza dover rileggere il file SARIF: id: zenzic uses: PythonWoods/zenzic-action@v1 with: - version: "0.7.0" + version: "0.7.1" - name: Mostra conteggio finding diff --git a/package-lock.json b/package-lock.json index 198995f..5b0a242 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "zenzic-docs", - "version": "0.0.0", + "version": "0.7.1", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "zenzic-docs", - "version": "0.0.0", + "version": "0.7.1", "dependencies": { "@docusaurus/core": "3.10.1", "@docusaurus/faster": "3.10.1", diff --git a/package.json b/package.json index 20e1233..8928981 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "zenzic-doc", - "version": "0.0.0", + "version": "0.7.1", "private": true, "scripts": { "docusaurus": "docusaurus", diff --git a/src/components/Homepage/Hero.tsx b/src/components/Homepage/Hero.tsx index f832f93..5c7cd57 100644 --- a/src/components/Homepage/Hero.tsx +++ b/src/components/Homepage/Hero.tsx @@ -25,7 +25,7 @@ export default function Hero(): React.JSX.Element {
- v0.7.0 "Quartz Maturity" Stable + v0.7.1 "Quartz Maturity" Stable

diff --git a/src/components/Homepage/Quickstart.tsx b/src/components/Homepage/Quickstart.tsx index e946cbc..1b9aa1c 100644 --- a/src/components/Homepage/Quickstart.tsx +++ b/src/components/Homepage/Quickstart.tsx @@ -48,7 +48,7 @@ export default function Quickstart(): React.JSX.Element { {/* Shell ready line */}
✓ - zenzic 0.7.0 · python 3.12 · ready + zenzic 0.7.1 · python 3.12 · ready

# explore the interactive lab (9 acts, zero setup) diff --git a/src/pages/index.tsx b/src/pages/index.tsx index d4c44f3..730b8a8 100644 --- a/src/pages/index.tsx +++ b/src/pages/index.tsx @@ -36,7 +36,7 @@ export default function Home(): React.JSX.Element { "name": "Zenzic", "operatingSystem": "Linux, macOS, Windows", "applicationCategory": "DeveloperApplication", - "softwareVersion": "0.7.0", + "softwareVersion": "0.7.1", "description": "High-performance, engine-agnostic, and security-hardened static analysis for Markdown documentation.", "url": "https://zenzic.dev", "offers": { From 6905008e8b66293660657f04e567cd4f611eeb57 Mon Sep 17 00:00:00 2001 From: PythonWoods Date: Fri, 8 May 2026 19:51:26 +0200 Subject: [PATCH 15/18] chore: add release-contracts guard and SPDX header to .bumpversion.toml --- .bumpversion.toml | 3 +++ justfile | 15 ++++++++++++++- 2 files changed, 17 insertions(+), 1 deletion(-) diff --git a/.bumpversion.toml b/.bumpversion.toml index aa5477a..3ba957c 100644 --- a/.bumpversion.toml +++ b/.bumpversion.toml @@ -1,3 +1,6 @@ +# SPDX-FileCopyrightText: 2026 PythonWoods +# SPDX-License-Identifier: Apache-2.0 + [tool.bumpversion] current_version = "0.7.1" parse = "(?P\\d+)\\.(?P\\d+)\\.(?P\\d+)" diff --git a/justfile b/justfile index f1da5e3..17be526 100644 --- a/justfile +++ b/justfile @@ -51,7 +51,7 @@ lint *args: uvx pre-commit run {{args}} # Recommended final local check (4-Gates Standard: pre-commit + build + codes parity) -verify: _check-hooks lint-all build verify-codes +verify: _check-hooks release-contracts lint-all build verify-codes # Verify Zxxx code parity between codes.py and finding-codes.mdx (EN + IT) verify-codes: @@ -134,3 +134,16 @@ _check-hooks: echo "👉 Fix it by running: uvx pre-commit install -t pre-push" echo "" fi + +# Enforce release contracts: dirty allowed only in release-dry. +release-contracts: + #!/usr/bin/env bash + set -euo pipefail + grep -qE '^version:' justfile + grep -qE '^release part:' justfile + grep -qE '^release-dry part:' justfile + grep -q -- '--dry-run --allow-dirty --verbose' justfile + if sed -n '/^release part:/,/^[^[:space:]].*:/p' justfile | tail -n +2 | grep -q -- '--allow-dirty'; then + echo "release-contracts failed: release part must not use --allow-dirty" + exit 1 + fi From adbc27bf61746f1b5cd45fc1771e812d872d4ac6 Mon Sep 17 00:00:00 2001 From: PythonWoods Date: Fri, 8 May 2026 20:04:22 +0200 Subject: [PATCH 16/18] feat(dx): add --short flag to release-dry --- justfile | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/justfile b/justfile index 17be526..243cda3 100644 --- a/justfile +++ b/justfile @@ -117,9 +117,18 @@ version: @uvx --from "bump-my-version==1.2.6" bump-my-version show current_version # Simulate a release bump without modifying any files -# Usage: just release-dry patch|minor|major -release-dry part: - uvx --from "bump-my-version==1.2.6" bump-my-version bump {{part}} --dry-run --allow-dirty --verbose +# Usage: just release-dry patch|minor|major [--short] +release-dry part *args: + #!/usr/bin/env bash + set -euo pipefail + _short=false + for _arg in {{args}}; do [[ "$_arg" == "--short" ]] && _short=true; done + if $_short; then + uvx --from "bump-my-version==1.2.6" bump-my-version bump {{part}} --dry-run --allow-dirty --verbose 2>&1 \ + | grep -E 'current version|New version will be|Dry run' + else + uvx --from "bump-my-version==1.2.6" bump-my-version bump {{part}} --dry-run --allow-dirty --verbose + fi doctor: @node -v || echo "node missing" @@ -141,7 +150,7 @@ release-contracts: set -euo pipefail grep -qE '^version:' justfile grep -qE '^release part:' justfile - grep -qE '^release-dry part:' justfile + grep -qE '^release-dry part' justfile grep -q -- '--dry-run --allow-dirty --verbose' justfile if sed -n '/^release part:/,/^[^[:space:]].*:/p' justfile | tail -n +2 | grep -q -- '--allow-dirty'; then echo "release-contracts failed: release part must not use --allow-dirty" From f725bcb71fdfc06884f2f0b32530ac6be0dd35ca Mon Sep 17 00:00:00 2001 From: PythonWoods Date: Fri, 8 May 2026 20:11:53 +0200 Subject: [PATCH 17/18] docs: add DX release recipes to CHANGELOG (EN+IT) --- CHANGELOG.it.md | 5 +++++ CHANGELOG.md | 5 +++++ 2 files changed, 10 insertions(+) diff --git a/CHANGELOG.it.md b/CHANGELOG.it.md index c99de38..50aec89 100644 --- a/CHANGELOG.it.md +++ b/CHANGELOG.it.md @@ -13,6 +13,11 @@ Le versioni seguono la linea di rilascio di Zenzic Core sotto la Branch Parity R #### Aggiunto +- **DX Release Recipes (Sprint DX):** Tutti e quattro i repository dell'ecosistema includono ora: + - `just version` — stampa la versione corrente tramite bump-my-version + - `just release-dry ` — dry-run verbose completo (mostra diff dei file) + - `just release-dry --short` — preview compatto (solo 3 righe essenziali) + - `just release-contracts` — valida i contratti architetturali del justfile, incluso in `verify` - **Branch Parity Rule — parity snapshot con Core v0.7.1:** Nessuna modifica al codice in questo repository (ecosistema Node/Docusaurus). Questa voce traccia l'allineamento con la release di allineamento infrastrutturale di Zenzic Core (fix della matrice diff --git a/CHANGELOG.md b/CHANGELOG.md index aeea465..99bf1cd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,11 @@ Versions track the Zenzic Core release line under the Branch Parity Rule. #### Added +- **DX Release Recipes (Sprint DX):** All four ecosystem repositories now include: + - `just version` — prints current version from bump-my-version + - `just release-dry ` — full verbose dry-run (shows file diffs) + - `just release-dry --short` — compact preview (3 essential lines only) + - `just release-contracts` — validates justfile architectural contracts, wired into `verify` - **Branch Parity Rule — snapshot parity with Core v0.7.1:** No code changes in this repository (Node/Docusaurus ecosystem). This entry tracks alignment with the Zenzic Core infrastructure alignment release (Boundary Testing matrix fix, Mypy floor From 1dd5bddae1000d13caea82a2c63b38e8b5f1fb92 Mon Sep 17 00:00:00 2001 From: PythonWoods Date: Sat, 9 May 2026 17:37:20 +0200 Subject: [PATCH 18/18] fix(security): bump fast-uri to 3.1.2 to resolve GHSA-q3j6-qgpj-74h6 --- package-lock.json | 13 +++++++------ package.json | 1 + 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/package-lock.json b/package-lock.json index 5b0a242..c30b0f0 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { - "name": "zenzic-docs", + "name": "zenzic-doc", "version": "0.7.1", "lockfileVersion": 3, "requires": true, "packages": { "": { - "name": "zenzic-docs", - "version": "0.7.1", + "name": "zenzic-doc", + "version": "0.7.1", "dependencies": { "@docusaurus/core": "3.10.1", "@docusaurus/faster": "3.10.1", @@ -14,6 +14,7 @@ "@mdx-js/react": "^3.0.0", "@tailwindcss/postcss": "^4.2.4", "clsx": "^2.0.0", + "fast-uri": "^3.1.2", "lucide-react": "^1.14.0", "prism-react-renderer": "^2.3.0", "react": "^19.0.0", @@ -10986,9 +10987,9 @@ "license": "MIT" }, "node_modules/fast-uri": { - "version": "3.1.0", - "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.0.tgz", - "integrity": "sha512-iPeeDKJSWf4IEOasVVrknXpaBV0IApz/gp7S2bb7Z4Lljbl2MGJRqInZiUrQwV16cpzw/D3S5j5Julj/gT52AA==", + "version": "3.1.2", + "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.2.tgz", + "integrity": "sha512-rVjf7ArG3LTk+FS6Yw81V1DLuZl1bRbNrev6Tmd/9RaroeeRRJhAt7jg/6YFxbvAQXUCavSoZhPPj6oOx+5KjQ==", "funding": [ { "type": "github", diff --git a/package.json b/package.json index 8928981..359a361 100644 --- a/package.json +++ b/package.json @@ -25,6 +25,7 @@ "@mdx-js/react": "^3.0.0", "@tailwindcss/postcss": "^4.2.4", "clsx": "^2.0.0", + "fast-uri": "^3.1.2", "lucide-react": "^1.14.0", "prism-react-renderer": "^2.3.0", "react": "^19.0.0",