From 6805dc560b18e9c3684aa68eecf6894e3eb3ff50 Mon Sep 17 00:00:00 2001 From: PythonWoods Date: Sun, 19 Apr 2026 19:13:15 +0200 Subject: [PATCH 01/13] docs(release): synchronize v0.6.1 documentation (EN/IT) and REUSE compliance --- .github/workflows/codeql.yml | 2 - .markdownlint-cli2.jsonc | 4 + LICENSES/Apache-2.0.txt | 190 ++++++++++++++++++ RELEASE.md | 5 +- REUSE.toml | 21 +- docs/community/_category_.json | 2 +- docs/community/contribute/_category_.json | 2 +- docs/guides/_category_.json | 2 +- docs/guides/adapters-config.mdx | 3 +- docs/guides/core-settings.mdx | 6 +- docs/guides/engines.mdx | 29 ++- docs/guides/migration.mdx | 29 ++- docs/internals/_category_.json | 2 +- docs/internals/adr/_category_.json | 2 +- docs/internals/architecture-overview.mdx | 28 +++ docs/internals/developers/_category_.json | 2 +- docs/internals/reference/_category_.json | 2 +- docs/internals/security/_category_.json | 2 +- docs/usage/_category_.json | 2 +- docs/usage/commands.mdx | 27 +++ docusaurus.config.ts | 6 +- eslint.config.mjs | 3 + .../current/community/_category_.json | 2 +- .../community/contribute/_category_.json | 2 +- .../current/guides/_category_.json | 2 +- .../current/guides/adapters-config.mdx | 3 +- .../current/guides/core-settings.mdx | 9 +- .../current/guides/engines.mdx | 29 ++- .../current/guides/migration.mdx | 30 ++- .../current/internals/_category_.json | 2 +- .../current/internals/adr/_category_.json | 2 +- .../internals/architecture-overview.mdx | 28 ++- .../internals/developers/_category_.json | 2 +- .../internals/reference/_category_.json | 2 +- .../internals/security/_category_.json | 2 +- .../current/usage/_category_.json | 2 +- .../current/usage/commands.mdx | 28 +++ src/components/Homepage/Features.tsx | 60 +++--- src/components/Homepage/Hero.tsx | 2 +- src/components/Homepage/QualityScore.tsx | 6 +- src/css/custom.css | 2 +- tsconfig.json | 3 - zenzic.toml | 8 +- 43 files changed, 492 insertions(+), 105 deletions(-) create mode 100644 LICENSES/Apache-2.0.txt diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index 2e0d07a..1fdda6f 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -48,5 +48,3 @@ jobs: - name: Perform CodeQL Analysis uses: github/codeql-action/analyze@v3 - - diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc index a9c5570..6705f95 100644 --- a/.markdownlint-cli2.jsonc +++ b/.markdownlint-cli2.jsonc @@ -1,3 +1,7 @@ +/* + * SPDX-FileCopyrightText: 2026 PythonWoods + * SPDX-License-Identifier: Apache-2.0 + */ { "$schema": "https://raw.githubusercontent.com/DavidAnson/markdownlint-cli2/main/schema/markdownlint-cli2-config-schema.json", "globs": [ diff --git a/LICENSES/Apache-2.0.txt b/LICENSES/Apache-2.0.txt new file mode 100644 index 0000000..624eb6a --- /dev/null +++ b/LICENSES/Apache-2.0.txt @@ -0,0 +1,190 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to the Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + Copyright 2025 Cell Location Analyzer Contributors + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/RELEASE.md b/RELEASE.md index 60684a3..6800e91 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -1,8 +1,11 @@ + + + # Release — zenzic-doc ## Current Status -> **v0.6.1rc2 "Obsidian Bastion (Hardened)" — Public Launch Active.** +> **v0.6.1 "Obsidian Glass (Stable)" — Public Launch Active.** The documentation site is open and publicly deployed. All embargo conditions have been satisfied. diff --git a/REUSE.toml b/REUSE.toml index 593639c..371c3c1 100644 --- a/REUSE.toml +++ b/REUSE.toml @@ -40,6 +40,12 @@ precedence = "aggregate" SPDX-FileCopyrightText = "2026 PythonWoods " SPDX-License-Identifier = "Apache-2.0" +[[annotations]] +path = "i18n/**/assets/**" +precedence = "aggregate" +SPDX-FileCopyrightText = "2026 PythonWoods " +SPDX-License-Identifier = "Apache-2.0" + # ── i18n translation files ─────────────────────────────────────────────────── [[annotations]] @@ -57,7 +63,20 @@ SPDX-License-Identifier = "Apache-2.0" # ── Project root — configuration ───────────────────────────────────────────── [[annotations]] -path = ["package.json", "tsconfig.json", "docusaurus.config.ts", "sidebars.ts", "tailwind.config.js"] +path = [ + "package.json", + "package-lock.json", + "tsconfig.json", + "docusaurus.config.ts", + "sidebars.ts", + "tailwind.config.js", + "eslint.config.mjs", + ".markdownlint-cli2.jsonc", + "RELEASE.md", + "zenzic.toml", + "justfile", + "**/*_category_.json" +] SPDX-FileCopyrightText = "2026 PythonWoods " SPDX-License-Identifier = "Apache-2.0" diff --git a/docs/community/_category_.json b/docs/community/_category_.json index bf94d8a..808fa07 100644 --- a/docs/community/_category_.json +++ b/docs/community/_category_.json @@ -5,4 +5,4 @@ "type": "generated-index", "description": "Contribute, report bugs, request features, and explore the project philosophy." } -} \ No newline at end of file +} diff --git a/docs/community/contribute/_category_.json b/docs/community/contribute/_category_.json index 7652806..d3e9e6f 100644 --- a/docs/community/contribute/_category_.json +++ b/docs/community/contribute/_category_.json @@ -5,4 +5,4 @@ "type": "generated-index", "description": "Bug reports, pull requests, change requests, and contribution guidelines." } -} \ No newline at end of file +} diff --git a/docs/guides/_category_.json b/docs/guides/_category_.json index a80c511..6ba3046 100644 --- a/docs/guides/_category_.json +++ b/docs/guides/_category_.json @@ -6,4 +6,4 @@ "type": "generated-index", "description": "Configuration reference, engine adapters, CI/CD integration, and migration." } -} \ No newline at end of file +} diff --git a/docs/guides/adapters-config.mdx b/docs/guides/adapters-config.mdx index c80debd..1bce197 100644 --- a/docs/guides/adapters-config.mdx +++ b/docs/guides/adapters-config.mdx @@ -87,7 +87,8 @@ Zenzic resolves the correct adapter automatically from `build_context.engine`: | `"mkdocs"` (default) | `mkdocs.yml` found | `MkDocsAdapter` — reads nav and i18n from `mkdocs.yml` | | `"mkdocs"` | `mkdocs.yml` absent, no locales | `VanillaAdapter` — no nav awareness | | `"zensical"` | `zensical.toml` found | `ZensicalAdapter` — reads nav from `zensical.toml` | -| `"zensical"` | `zensical.toml` absent | **Error** — `zensical.toml` is required | +| `"zensical"` | `zensical.toml` absent, `mkdocs.yml` found | `ZensicalAdapter` — **Transparent Proxy** using `mkdocs.yml` | +| `"docusaurus"` | `docusaurus.config.ts` found | `DocusaurusAdapter` — reads configuration statically | | any unknown string | — | `VanillaAdapter` — no registered adapter for this engine | ### Vanilla mode diff --git a/docs/guides/core-settings.mdx b/docs/guides/core-settings.mdx index 842c861..9fb362a 100644 --- a/docs/guides/core-settings.mdx +++ b/docs/guides/core-settings.mdx @@ -59,9 +59,9 @@ images. Leading slashes are stripped, so `"assets/favicon.svg"` and `"/assets/favicon.svg"` are equivalent. -:::warning[Breaking change in v0.6.0a2] -Prior versions treated each entry as a literal path and used exact set subtraction. -Starting from v0.6.0a2, every entry is treated as an `fnmatch` pattern. +:::warning[Breaking change in v0.6.0] +Prior versions treated each entry as a literal path. +Starting from v0.6.0, every entry is treated as an `fnmatch` pattern. Existing literal paths continue to work — they simply match themselves. ::: diff --git a/docs/guides/engines.mdx b/docs/guides/engines.mdx index 2a80c68..96aa990 100644 --- a/docs/guides/engines.mdx +++ b/docs/guides/engines.mdx @@ -189,16 +189,19 @@ using Python's `tomllib` — **zero YAML**. No `mkdocs.yml` is read or required. engine = "zensical" ``` -If `zensical.toml` is **absent** when `engine = "zensical"` is declared, Zenzic raises -`ConfigurationError` immediately: +### Transparent Proxy (Migration Bridge) + +To facilitate a smooth migration from MkDocs to Zensical, the adapter implements a **Transparent Proxy** mode. If `zensical.toml` is **absent** but `mkdocs.yml` is present in the project root, the Zensical adapter will automatically use the MkDocs configuration as a bridge. + +This allows you to test Zenzic with the Zensical engine even before you have fully committed to a native `zensical.toml`. When this happens, the Sentinel banner will notify you: ```text -ConfigurationError: engine 'zensical' declared in zenzic.toml but zensical.toml is missing -hint: create zensical.toml or set engine = 'mkdocs' for MkDocs projects +SENTINEL: Zensical engine active via mkdocs.yml compatibility bridge. ``` -There is no fallback. There is no silent degradation. Engine identity must be provable from -the files on disk. +:::warning[Structural Custodian Rule] +While this bridge allows Zenzic to run, Zensical itself may handle some MkDocs features differently. Use the bridge as a temporary safety net during migration, and aim for a native `zensical.toml` to achieve full parity. +::: ### zensical.toml nav format @@ -270,6 +273,20 @@ locales = ["it", "fr"] When `locales` is empty, Zenzic reads locale information from the `i18n` block in `docusaurus.config.ts`. +### Versioning support + +Zenzic supports Docusaurus **multi-version documentation** out of the box. It identifies: + +1. **Version list** — read from `versions.json` in the project root. +2. **Versioned content** — discovered under `versioned_docs/version-{version}/`. +3. **Versioned translations** — discovered under `i18n/{locale}/docusaurus-plugin-content-docs/version-{version}/`. + +The Virtual Site Map automatically maps these paths to their correct canonical URLs (e.g., `/docs/1.0.0/intro/`), allowing Zenzic to validate links across versions without requiring a build. + +:::tip[Ghost Routing] +Versioned routes are treated as **Ghost Routes**: they are always considered reachable because Docusaurus automatically generates navigation for versioned documentation trees. +::: + ### i18n layout Docusaurus stores translations in a deep directory structure: diff --git a/docs/guides/migration.mdx b/docs/guides/migration.mdx index d5a2cc1..b7ecc95 100644 --- a/docs/guides/migration.mdx +++ b/docs/guides/migration.mdx @@ -218,8 +218,19 @@ not depend on any build engine being functional. Install Zensical alongside (or instead of) MkDocs: ```bash -uv add --dev zensical # recommended -# or: pip install zensical +uv pip install zensical # or: pip install zensical +``` + +You can now test your documentation against the Zensical engine without even creating a `zensical.toml`. By running Zenzic with the Zensical engine, the **Transparent Proxy** mode activates: + +```bash +zenzic check all --engine zensical +``` + +Zenzic will read your existing `mkdocs.yml` and validate how Zensical would interpret it. Look for the Sentinel banner to confirm the bridge is active: + +```text +SENTINEL: Zensical engine active via mkdocs.yml compatibility bridge. ``` Run the documentation build to verify it produces correct output: @@ -262,10 +273,12 @@ nav = [ ] ``` -:::warning[Enforcement contract] -Once `engine = "zensical"` is declared in `zenzic.toml`, `zensical.toml` **must** exist. -Zenzic raises a `ConfigurationError` immediately if it is absent — there is no silent -fallback to `mkdocs.yml`. This is intentional: engine identity must be provable. +:::tip[Flexible Identity & Structural Custodian] +If `engine = "zensical"` is declared but `zensical.toml` does not yet exist, Zenzic will natively fall back to reading your existing `mkdocs.yml` (the Transparent Bridge). +This allows you to switch your engine and keep your legacy configuration file during the transition, without breaking your validation pipeline. Zenzic acts as a structural custodian: it won't force you to change your configuration format prematurely. + +Note: While operating via the compatibility bridge, Zenzic will issue warnings if your `mkdocs.yml` contains MkDocs-specific settings that Zensical ignores, such as: +`remote_branch`, `remote_name`, `exclude_docs`, `draft_docs`, `not_in_nav`, `validation`, `strict`, `hooks`, and `watch`. ::: ### Phase 4 — Verify link integrity @@ -297,7 +310,7 @@ supports all of them with the same quality guarantee: | Path | `engine` in `zenzic.toml` | What Zenzic validates | | :--- | :--- | :--- | | Stay on MkDocs 1.x | `"mkdocs"` | Full MkDocs 1.x structural contract | -| Switch to Zensical | `"zensical"` | Zensical nav + TOML identity contract | +| Switch to Zensical | `"zensical"` | Zensical nav (via TOML or legacy YAML bridge) | | Migrate to another engine | `"mkdocs"` during transition, then adapter | Source integrity throughout | | Evaluate without committing | `--engine mkdocs` or `--engine zensical` (CLI flag) | Dry-run compatibility check | @@ -340,5 +353,5 @@ engine = "zensical" | Compatibility dry-run | `zenzic check all --engine zensical` | Structural issues with Zensical adapter | | After build switch | `zenzic check all` | Same issues as before | | Regression check | `zenzic diff` | Delta = 0 | -| Identity enforcement | `engine = "zensical"` in `zenzic.toml` | Requires `zensical.toml` | +| Flexible identity | `engine = "zensical"` in `zenzic.toml` | Uses `zensical.toml` or falls back to `mkdocs.yml` | | Final gate | `zenzic diff --threshold 0` | Exit 0 only if score did not drop | diff --git a/docs/internals/_category_.json b/docs/internals/_category_.json index 43ad6c7..8ddd159 100644 --- a/docs/internals/_category_.json +++ b/docs/internals/_category_.json @@ -5,4 +5,4 @@ "type": "generated-index", "description": "Architecture, ADRs, security model, and developer references." } -} \ No newline at end of file +} diff --git a/docs/internals/adr/_category_.json b/docs/internals/adr/_category_.json index e3b49a9..0ee8215 100644 --- a/docs/internals/adr/_category_.json +++ b/docs/internals/adr/_category_.json @@ -5,4 +5,4 @@ "type": "generated-index", "description": "Recorded architectural decisions and their rationale." } -} \ No newline at end of file +} diff --git a/docs/internals/architecture-overview.mdx b/docs/internals/architecture-overview.mdx index f17c48a..37a7dea 100644 --- a/docs/internals/architecture-overview.mdx +++ b/docs/internals/architecture-overview.mdx @@ -252,6 +252,34 @@ class RouteMetadata: slug: str | None = None # Frontmatter slug override route_base_path: str = "/" # URL prefix from docs plugin preset is_proxy: bool = False # True for build-generated routes with no source file + version: str | None = None # Optional version label (Docusaurus support) +``` + +--- + +## Virtual Site Map (VSM) {#vsm} + +The Virtual Site Map is Zenzic's **single source of truth for routing**. It is a pure-data structure (a mapping of `canonical_url` string to `Route` objects) constructed by the `VSMBuilder` by combining adapter knowledge with filesystem discovery. + +### Versioning & Multi-Doc Support {#vsm-versioning} + +Starting with v0.6.1 "Obsidian Glass", the VSM is **version-aware**. For adapters that support multi-version documentation (currently `DocusaurusAdapter`), the VSM builder: + +1. **Identifies version boundaries** via the adapter's extended root discovery. +2. **Tags routes** with their respective version label in `RouteMetadata`. +3. **Resolves cross-links** within the same version context first, preventing version-skew in link validation. + +Versioned routes are often treated as **Ghost Routes** — they are marked `REACHABLE` even if they do not appear in the primary navigation file, as the build engine is assumed to manage version-specific sidebars automatically. + +### Offline Mode & Flat URL Resolution {#vsm-offline} + +The `--offline` flag triggers a global architectural shift in how the VSM resolves URLs. When active: + +1. **`offline_mode`** is set to `True` in the `BuildContext`. +2. **Adapters force `use_directory_urls = False`**, overriding any engine-specific configuration. +3. **`map_url()`** produces flat `.html` paths (e.g., `guide/install.md` → `/guide/install.html`) instead of directory-style slugs. + +This ensures that Zenzic remains a **Structural Custodian** for documentation distributed on filesystems where directory-index resolution (e.g., `/page/` → `/page/index.html`) is unavailable. ``` ### Built-in Adapters {#built-in-adapters} diff --git a/docs/internals/developers/_category_.json b/docs/internals/developers/_category_.json index 357efed..c36c974 100644 --- a/docs/internals/developers/_category_.json +++ b/docs/internals/developers/_category_.json @@ -5,4 +5,4 @@ "type": "generated-index", "description": "Plugin SDK, adapter authoring, and contributor tooling." } -} \ No newline at end of file +} diff --git a/docs/internals/reference/_category_.json b/docs/internals/reference/_category_.json index b5b3abe..414c586 100644 --- a/docs/internals/reference/_category_.json +++ b/docs/internals/reference/_category_.json @@ -5,4 +5,4 @@ "type": "generated-index", "description": "Internal API surface and data model reference." } -} \ No newline at end of file +} diff --git a/docs/internals/security/_category_.json b/docs/internals/security/_category_.json index 9257d85..35ee255 100644 --- a/docs/internals/security/_category_.json +++ b/docs/internals/security/_category_.json @@ -5,4 +5,4 @@ "type": "generated-index", "description": "Threat model, Shield internals, and Blood Sentinel." } -} \ No newline at end of file +} diff --git a/docs/usage/_category_.json b/docs/usage/_category_.json index 41cdfef..334ff8e 100644 --- a/docs/usage/_category_.json +++ b/docs/usage/_category_.json @@ -5,4 +5,4 @@ "type": "generated-index", "description": "Install, configure, and run Zenzic on your documentation." } -} \ No newline at end of file +} diff --git a/docs/usage/commands.mdx b/docs/usage/commands.mdx index 77df1ac..9260e91 100644 --- a/docs/usage/commands.mdx +++ b/docs/usage/commands.mdx @@ -31,6 +31,7 @@ zenzic check all --format json # Machine-readable output zenzic check all --exit-zero # Report issues but always exit 0 zenzic check all --quiet # Minimal one-line output for pre-commit and CI hooks zenzic check all --engine mkdocs # Override detected build engine adapter +zenzic check all --offline # Force flat URL resolution (e.g. for USB / intranet builds) zenzic check links --show-info # Show info-level findings (e.g. circular links) ``` @@ -87,6 +88,32 @@ zenzic check all --show-info zenzic check all --quiet ``` +### `--offline` + +`--offline` is available on `check all`, `check links`, and `check orphans`. It forces +all adapters (MkDocs and Zensical) to resolve URLs **without** `use_directory_urls`, +producing flat `.html` paths instead of clean directory-based slugs. + +Use this flag when linting documentation that will be distributed as static files — for +example, bundled onto a USB drive or served over an intranet without a web server. + +```bash +zenzic check all --offline # flat URL mode: guide/install.md → /guide/install.html +zenzic check links --offline +zenzic check orphans --offline +``` + +When active, the Sentinel banner displays: + +```text +SENTINEL: [Offline Mode Active: forcing flat URL structure] +``` + +:::note[Engine parity] +The `--offline` flag has **identical behaviour** on both the MkDocs and Zensical adapters. +This ensures Zenzic remains a consistent Structural Custodian regardless of your build engine. +::: + --- ## Initialization diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 608706b..aae4361 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -90,7 +90,7 @@ const config: Config = { { type: 'html', position: 'left', - value: 'v0.6.1rc2', + value: 'v0.6.1', }, { type: 'localeDropdown', @@ -106,7 +106,7 @@ const config: Config = { footer: { style: 'dark', links: [], - copyright: `© ${new Date().getFullYear()} PythonWoods. Zenzic v0.6.1rc2. Apache-2.0 License. · Python 3.11+ · Zero runtime dependencies`, + copyright: `© ${new Date().getFullYear()} PythonWoods. Zenzic v0.6.1. Apache-2.0 License. · Python 3.11+ · Zero runtime dependencies`, }, prism: { theme: prismThemes.github, @@ -117,4 +117,4 @@ const config: Config = { } satisfies Preset.ThemeConfig, }; -export default config; \ No newline at end of file +export default config; diff --git a/eslint.config.mjs b/eslint.config.mjs index de1de7d..fd4bea1 100644 --- a/eslint.config.mjs +++ b/eslint.config.mjs @@ -1,3 +1,6 @@ +// SPDX-FileCopyrightText: 2026 PythonWoods +// SPDX-License-Identifier: Apache-2.0 + import js from '@eslint/js'; import globals from 'globals'; import react from 'eslint-plugin-react'; diff --git a/i18n/it/docusaurus-plugin-content-docs/current/community/_category_.json b/i18n/it/docusaurus-plugin-content-docs/current/community/_category_.json index 223b95c..3ad7f71 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/community/_category_.json +++ b/i18n/it/docusaurus-plugin-content-docs/current/community/_category_.json @@ -5,4 +5,4 @@ "type": "generated-index", "description": "Contribuisci, segnala bug, richiedi funzionalità ed esplora la filosofia del progetto." } -} \ No newline at end of file +} diff --git a/i18n/it/docusaurus-plugin-content-docs/current/community/contribute/_category_.json b/i18n/it/docusaurus-plugin-content-docs/current/community/contribute/_category_.json index 6a04546..e382a7d 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/community/contribute/_category_.json +++ b/i18n/it/docusaurus-plugin-content-docs/current/community/contribute/_category_.json @@ -5,4 +5,4 @@ "type": "generated-index", "description": "Segnalazioni bug, pull request, richieste di modifica e linee guida per contribuire." } -} \ No newline at end of file +} diff --git a/i18n/it/docusaurus-plugin-content-docs/current/guides/_category_.json b/i18n/it/docusaurus-plugin-content-docs/current/guides/_category_.json index 9d4223d..05307ad 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/guides/_category_.json +++ b/i18n/it/docusaurus-plugin-content-docs/current/guides/_category_.json @@ -6,4 +6,4 @@ "type": "generated-index", "description": "Riferimento configurazione, adapter, CI/CD e migrazione." } -} \ No newline at end of file +} diff --git a/i18n/it/docusaurus-plugin-content-docs/current/guides/adapters-config.mdx b/i18n/it/docusaurus-plugin-content-docs/current/guides/adapters-config.mdx index 03c9f7d..90ab86b 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/guides/adapters-config.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/guides/adapters-config.mdx @@ -77,7 +77,8 @@ una pagina tradotta a una pagina che esiste solo nel locale di default viene sop | `"mkdocs"` (default) | `mkdocs.yml` trovato | `MkDocsAdapter` — legge nav e i18n da `mkdocs.yml` | | `"mkdocs"` | `mkdocs.yml` assente, nessun locale | `VanillaAdapter` — nessuna consapevolezza nav | | `"zensical"` | `zensical.toml` trovato | `ZensicalAdapter` — legge nav da `zensical.toml` | -| `"zensical"` | `zensical.toml` assente | **Errore** — `zensical.toml` è richiesto | +| `"zensical"` | `zensical.toml` assente, `mkdocs.yml` trovato | `ZensicalAdapter` — **Proxy Trasparente** usando `mkdocs.yml` | +| `"docusaurus"` | `docusaurus.config.ts` trovato | `DocusaurusAdapter` — legge la configurazione staticamente | | qualsiasi stringa sconosciuta | — | `VanillaAdapter` — nessun adapter registrato per questo motore | ### Modalità Vanilla diff --git a/i18n/it/docusaurus-plugin-content-docs/current/guides/core-settings.mdx b/i18n/it/docusaurus-plugin-content-docs/current/guides/core-settings.mdx index 7aa21b8..f4cc15e 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/guides/core-settings.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/guides/core-settings.mdx @@ -59,11 +59,10 @@ immagini di anteprima social. Gli slash iniziali vengono rimossi, quindi `"assets/favicon.svg"` e `"/assets/favicon.svg"` sono equivalenti. -:::warning[Modifica incompatibile nella v0.6.0a2] -Le versioni precedenti trattavano ogni voce come un percorso letterale e usavano la -sottrazione esatta di set. A partire dalla v0.6.0a2, ogni voce è trattata come un pattern -`fnmatch`. I percorsi letterali esistenti continuano a funzionare — corrispondono -semplicemente a se stessi. +:::warning[Modifica incompatibile nella v0.6.0] +Le versioni precedenti trattavano ogni voce come un percorso letterale. +A partire dalla v0.6.0, ogni voce è trattata come un pattern `fnmatch`. +I percorsi letterali esistenti continuano a funzionare: corrispondono semplicemente a se stessi. ::: ```toml diff --git a/i18n/it/docusaurus-plugin-content-docs/current/guides/engines.mdx b/i18n/it/docusaurus-plugin-content-docs/current/guides/engines.mdx index 85d7107..4f257d9 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/guides/engines.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/guides/engines.mdx @@ -196,16 +196,19 @@ né richiesto. engine = "zensical" ``` -Se `zensical.toml` è **assente** quando `engine = "zensical"` è dichiarato, Zenzic lancia -`ConfigurationError` immediatamente: +### Proxy Trasparente (Ponte di Migrazione) + +Per facilitare una migrazione fluida da MkDocs a Zensical, l'adapter implementa una modalità **Proxy Trasparente**. Se `zensical.toml` è **assente** ma `mkdocs.yml` è presente nella root del progetto, l'adapter Zensical utilizzerà automaticamente la configurazione MkDocs come ponte. + +Questo permette di testare Zenzic con l'engine Zensical ancora prima di aver completato il passaggio a un file `zensical.toml` nativo. In questo caso, il banner Sentinel ti avviserà: ```text -ConfigurationError: engine 'zensical' declared in zenzic.toml but zensical.toml is missing -hint: create zensical.toml or set engine = 'mkdocs' for MkDocs projects +SENTINEL: Zensical engine active via mkdocs.yml compatibility bridge. ``` -Non esiste fallback. Non esiste degradazione silenziosa. L'identità del motore deve essere -dimostrabile dai file presenti su disco. +:::warning[Regola del Custode Strutturale] +Sebbene questo ponte permetta a Zenzic di funzionare, Zensical stesso potrebbe gestire alcune feature di MkDocs in modo diverso. Usa il ponte come rete di sicurezza temporanea durante la migrazione e punta a un file `zensical.toml` nativo per ottenere la piena parità. +::: ### Formato nav di zensical.toml @@ -276,6 +279,20 @@ locales = ["it", "fr"] Quando `locales` è vuoto, Zenzic legge le informazioni sui locale dal blocco `i18n` in `docusaurus.config.ts`. +### Supporto al versioning + +Zenzic supporta nativamente la **documentazione multi-versione** di Docusaurus. Identifica: + +1. **Lista versioni** — letta da `versions.json` nella root del progetto. +2. **Contenuto versionato** — scoperto sotto `versioned_docs/version-{version}/`. +3. **Traduzioni versionate** — scoperte sotto `i18n/{locale}/docusaurus-plugin-content-docs/version-{version}/`. + +La Virtual Site Map mappa automaticamente questi percorsi ai rispettivi URL canonici (es. `/docs/1.0.0/intro/`), permettendo a Zenzic di validare i link tra le versioni senza richiedere una build. + +:::tip[Ghost Routing] +Le rotte versionate sono trattate come **Ghost Routes**: sono sempre considerate raggiungibili perché Docusaurus genera automaticamente la navigazione per gli alberi di documentazione versionati. +::: + ### Layout i18n Docusaurus memorizza le traduzioni in una struttura di directory profonda: diff --git a/i18n/it/docusaurus-plugin-content-docs/current/guides/migration.mdx b/i18n/it/docusaurus-plugin-content-docs/current/guides/migration.mdx index e990227..145ac71 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/guides/migration.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/guides/migration.mdx @@ -221,8 +221,19 @@ sorgenti — non dipende dal funzionamento di alcun motore di build. Installa Zensical insieme a (o al posto di) MkDocs: ```bash -uv add --dev zensical # raccomandato -# oppure: pip install zensical +uv pip install zensical # oppure: pip install zensical +``` + +Ora puoi testare la tua documentazione contro il motore Zensical senza nemmeno creare un file `zensical.toml`. Eseguendo Zenzic con l'engine Zensical, si attiva la modalità **Proxy Trasparente**: + +```bash +zenzic check all --engine zensical +``` + +Zenzic leggerà il tuo file `mkdocs.yml` esistente e validerà come Zensical lo interpreterebbe. Cerca il banner Sentinel per confermare che il ponte è attivo: + +```text +SENTINEL: Zensical engine active via mkdocs.yml compatibility bridge. ``` Esegui la build della documentazione per verificare che produca output corretto: @@ -266,11 +277,12 @@ nav = [ ] ``` -:::warning[Contratto di enforcement] -Una volta dichiarato `engine = "zensical"` in `zenzic.toml`, `zensical.toml` **deve** -esistere. Zenzic solleva un `ConfigurationError` immediatamente se è assente — non c'è -fallback silenzioso a `mkdocs.yml`. Questo è intenzionale: l'identità dell'engine deve -essere provabile. +:::tip[Identità Flessibile & Custode Strutturale] +Se `engine = "zensical"` è dichiarato ma `zensical.toml` non esiste ancora, Zenzic eseguirà nativamente un fallback leggendo il tuo `mkdocs.yml` esistente (il Proxy Trasparente). +Questo ti permette di cambiare engine e mantenere il file di configurazione legacy durante la transizione, senza interrompere la pipeline di validazione. Zenzic agisce come un custode strutturale: non ti costringerà a cambiare formato di configurazione prematuramente. + +Nota: Mentre opera tramite il bridge di compatibilità, Zenzic emetterà dei warning se il tuo `mkdocs.yml` contiene impostazioni specifiche di MkDocs che Zensical ignora, come: +`remote_branch`, `remote_name`, `exclude_docs`, `draft_docs`, `not_in_nav`, `validation`, `strict`, `hooks` e `watch`. ::: ### Fase 4 — Verifica l'integrità dei link @@ -302,7 +314,7 @@ le supporta tutte con la stessa garanzia di qualità: | Percorso | `engine` in `zenzic.toml` | Cosa valida Zenzic | | :--- | :--- | :--- | | Rimane su MkDocs 1.x | `"mkdocs"` | Contratto strutturale completo MkDocs 1.x | -| Passa a Zensical | `"zensical"` | Nav Zensical + contratto identità TOML | +| Passa a Zensical | `"zensical"` | Nav Zensical (via TOML o bridge legacy YAML) | | Migra a un altro motore | `"mkdocs"` durante transizione, poi adapter | Integrità sorgenti durante il cambio | | Valuta senza impegnarsi | flag CLI `--engine mkdocs` o `--engine zensical` | Controllo compatibilità dry-run | @@ -345,5 +357,5 @@ engine = "zensical" | Dry-run compatibilità | `zenzic check all --engine zensical` | Problemi strutturali con adapter Zensical | | Dopo il cambio di build | `zenzic check all` | Stessi problemi di prima | | Controllo regressioni | `zenzic diff` | Delta = 0 | -| Enforcement identità | `engine = "zensical"` in `zenzic.toml` | Richiede `zensical.toml` | +| Identità flessibile | `engine = "zensical"` in `zenzic.toml` | Usa `zensical.toml` o esegue il fallback a `mkdocs.yml` | | Gate finale | `zenzic diff --threshold 0` | Exit 0 solo se il punteggio non è diminuito | diff --git a/i18n/it/docusaurus-plugin-content-docs/current/internals/_category_.json b/i18n/it/docusaurus-plugin-content-docs/current/internals/_category_.json index b9ce45e..2a1cbab 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/internals/_category_.json +++ b/i18n/it/docusaurus-plugin-content-docs/current/internals/_category_.json @@ -5,4 +5,4 @@ "type": "generated-index", "description": "Architettura, ADR, modello di sicurezza e riferimenti per sviluppatori." } -} \ No newline at end of file +} diff --git a/i18n/it/docusaurus-plugin-content-docs/current/internals/adr/_category_.json b/i18n/it/docusaurus-plugin-content-docs/current/internals/adr/_category_.json index 7d68c01..d75f9dc 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/internals/adr/_category_.json +++ b/i18n/it/docusaurus-plugin-content-docs/current/internals/adr/_category_.json @@ -5,4 +5,4 @@ "type": "generated-index", "description": "Decisioni architetturali registrate e le loro motivazioni." } -} \ No newline at end of file +} diff --git a/i18n/it/docusaurus-plugin-content-docs/current/internals/architecture-overview.mdx b/i18n/it/docusaurus-plugin-content-docs/current/internals/architecture-overview.mdx index c5e4775..069482a 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/internals/architecture-overview.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/internals/architecture-overview.mdx @@ -126,6 +126,33 @@ Gli adapter sono il meccanismo che permette a Zenzic di supportare diversi motor - `url` — URL canonico della pagina - `status` — stato della route: `REACHABLE`, `ORPHAN_BUT_EXISTING`, `IGNORED` - `source_path` — percorso del file sorgente relativo a `docs_root` +- `version` — etichetta opzionale della versione (supporto Docusaurus) + +--- + +## Virtual Site Map (VSM) {#vsm} + +La Virtual Site Map è l'**unica fonte di verità per il routing** di Zenzic. È una struttura dati pura (una mappa tra stringhe `canonical_url` e oggetti `Route`) costruita dal `VSMBuilder` combinando la conoscenza degli adapter con la scoperta del filesystem. + +### Versioning e Supporto Multi-Doc {#vsm-versioning} + +A partire dalla v0.6.1 "Obsidian Glass", la VSM è **consapevole delle versioni**. Per gli adapter che supportano la documentazione multi-versione (attualmente `DocusaurusAdapter`), il VSM builder: + +1. **Identifica i confini di versione** tramite la scoperta estesa della root dell'adapter. +2. **Etichetta le route** con la rispettiva versione in `RouteMetadata`. +3. **Risolve i cross-link** dando priorità al contesto della stessa versione, prevenendo la "version-skew" nella validazione dei link. + +Le route versionate sono spesso trattate come **Ghost Routes** — sono marcate come `REACHABLE` anche se non appaiono nel file di navigazione principale, poiché si assume che il motore di build gestisca automaticamente le sidebar specifiche per versione. + +### Modalità Offline e Risoluzione URL Flat {#vsm-offline} + +Il flag `--offline` innesca un cambiamento architetturale globale nel modo in cui la VSM risolve gli URL. Quando attivo: + +1. **`offline_mode`** viene impostato a `True` nel `BuildContext`. +2. **Gli adapter forzano `use_directory_urls = False`**, sovrascrivendo qualsiasi configurazione specifica del motore. +3. **`map_url()`** produce percorsi `.html` piatti (es. `guida/install.md` → `/guida/install.html`) invece di slug in stile directory. + +Questo garantisce che Zenzic rimanga un **Custode Strutturale** anche per la documentazione distribuita su filesystem dove la risoluzione dell'indice di directory (es. `/pagina/` → `/pagina/index.html`) non è disponibile. ### Adapter disponibili @@ -358,4 +385,3 @@ Le nuove integrazioni seguono lo stesso schema: 4. Usa `ZenzicConfig.load()` + le funzioni di controllo del core — non avviare mai sottoprocessi shell. Il package `zenzic.integrations` è intenzionalmente snello: non contiene logica condivisa, solo hook per-motore. Tutta l'intelligenza vive in `zenzic.core`. - diff --git a/i18n/it/docusaurus-plugin-content-docs/current/internals/developers/_category_.json b/i18n/it/docusaurus-plugin-content-docs/current/internals/developers/_category_.json index 262d942..c29526d 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/internals/developers/_category_.json +++ b/i18n/it/docusaurus-plugin-content-docs/current/internals/developers/_category_.json @@ -5,4 +5,4 @@ "type": "generated-index", "description": "Plugin SDK, creazione adapter e strumenti per contributori." } -} \ No newline at end of file +} diff --git a/i18n/it/docusaurus-plugin-content-docs/current/internals/reference/_category_.json b/i18n/it/docusaurus-plugin-content-docs/current/internals/reference/_category_.json index a3710ce..68e11b4 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/internals/reference/_category_.json +++ b/i18n/it/docusaurus-plugin-content-docs/current/internals/reference/_category_.json @@ -5,4 +5,4 @@ "type": "generated-index", "description": "Superficie API interna e riferimento del modello dati." } -} \ No newline at end of file +} diff --git a/i18n/it/docusaurus-plugin-content-docs/current/internals/security/_category_.json b/i18n/it/docusaurus-plugin-content-docs/current/internals/security/_category_.json index 12dd80f..45e2a49 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/internals/security/_category_.json +++ b/i18n/it/docusaurus-plugin-content-docs/current/internals/security/_category_.json @@ -5,4 +5,4 @@ "type": "generated-index", "description": "Modello di minaccia, Shield e Blood Sentinel." } -} \ No newline at end of file +} diff --git a/i18n/it/docusaurus-plugin-content-docs/current/usage/_category_.json b/i18n/it/docusaurus-plugin-content-docs/current/usage/_category_.json index 973596e..d7f80e9 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/usage/_category_.json +++ b/i18n/it/docusaurus-plugin-content-docs/current/usage/_category_.json @@ -5,4 +5,4 @@ "type": "generated-index", "description": "Installa, configura ed esegui Zenzic sulla tua documentazione." } -} \ No newline at end of file +} diff --git a/i18n/it/docusaurus-plugin-content-docs/current/usage/commands.mdx b/i18n/it/docusaurus-plugin-content-docs/current/usage/commands.mdx index 89ea071..0c0e268 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/usage/commands.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/usage/commands.mdx @@ -31,6 +31,7 @@ zenzic check all --format json # Output machine-readable zenzic check all --exit-zero # Segnala problemi ma esce sempre con codice 0 zenzic check all --quiet # Output minimale a riga singola per pre-commit e CI zenzic check all --engine mkdocs # Sovrascrive il motore rilevato +zenzic check all --offline # Forza URL piatti (es. per build su USB o rete intranet) zenzic check links --show-info # Mostra finding di livello info (es. link circolari) ``` @@ -88,6 +89,33 @@ zenzic check all --show-info zenzic check all --quiet ``` +### `--offline` + +`--offline` è disponibile su `check all`, `check links` e `check orphans`. Forza +tutti gli adapter (MkDocs e Zensical) a risolvere gli URL **senza** `use_directory_urls`, +producendo percorsi `.html` piatti invece di slug clean basati su directory. + +Usalo quando esegui il linting di documentazione distribuita come file statici — ad esempio +su chiavetta USB o su rete intranet senza web server. + +```bash +zenzic check all --offline # Modalità URL piatti: guide/install.md → /guide/install.html +zenzic check links --offline +zenzic check orphans --offline +``` + +Quando attivo, il banner Sentinel mostra: + +```text +SENTINEL: [Offline Mode Active: forcing flat URL structure] +``` + +:::note[Parità tra engine] +Il flag `--offline` ha un **comportamento identico** su entrambi gli adapter MkDocs e Zensical. +Questo garantisce che Zenzic resti un Custode Strutturale coerente indipendentemente dal tuo +motore di build. +::: + --- ## Inizializzazione diff --git a/src/components/Homepage/Features.tsx b/src/components/Homepage/Features.tsx index d9c08df..b5f9d1f 100644 --- a/src/components/Homepage/Features.tsx +++ b/src/components/Homepage/Features.tsx @@ -54,41 +54,41 @@ export default function Features(): React.JSX.Element {
- } - title={Broken links} - desc={Detects dead internal links, missing anchors, and unreachable URLs before the build runs.} + } + title={Broken links} + desc={Detects dead internal links, missing anchors, and unreachable URLs before the build runs.} /> - } - title={Orphan pages} - desc={ {str} }}>{'Finds .md files that exist on disk but are absent from the site navigation.'}} + } + title={Orphan pages} + desc={ {str} }}>{'Finds .md files that exist on disk but are absent from the site navigation.'}} /> - } - title={Invalid snippets} - desc={Compiles every fenced Python block. Catches syntax errors before readers copy-paste code.} + } + title={Invalid snippets} + desc={Compiles every fenced Python block. Catches syntax errors before readers copy-paste code.} /> - } - title={Placeholder stubs} - desc={ {str} }}>{'Flags pages below a word-count threshold or containing patterns like TODO, WIP.'}} + } + title={Placeholder stubs} + desc={ {str} }}>{'Flags pages below a word-count threshold or containing patterns like TODO, WIP.'}} /> - } - title={Unused assets} - desc={ {str} }}>{'Reports images and files that exist in docs/ but are never referenced by any page.'}} + } + title={Unused assets} + desc={ {str} }}>{'Reports images and files that exist in docs/ but are never referenced by any page.'}} /> - } - title={Zenzic Shield} - desc={ {str} }}>{'Scans every URL for leaked credentials - API keys, tokens. Exits with code 2 immediately.'}} + } + title={Zenzic Shield} + desc={ {str} }}>{'Scans every URL for leaked credentials - API keys, tokens. Exits with code 2 immediately.'}} />
diff --git a/src/components/Homepage/Hero.tsx b/src/components/Homepage/Hero.tsx index 2368f1c..fcb5c80 100644 --- a/src/components/Homepage/Hero.tsx +++ b/src/components/Homepage/Hero.tsx @@ -20,7 +20,7 @@ export default function Hero(): React.JSX.Element {
{/* Stealth Logo */} Zenzic Icon - +
diff --git a/src/components/Homepage/QualityScore.tsx b/src/components/Homepage/QualityScore.tsx index 6201cfb..6c50be1 100644 --- a/src/components/Homepage/QualityScore.tsx +++ b/src/components/Homepage/QualityScore.tsx @@ -17,7 +17,7 @@ function ScoreSubRow({icon, label, value}: {icon: ReactNode; label: ReactNode; v } function ScoreRow({color, label, value}: {color: 'sky' | 'rose'; label: ReactNode; value: ReactNode}): React.JSX.Element { - const palette = color === 'sky' + const palette = color === 'sky' ? { ring: 'border-sky-500/30 bg-sky-500/10', dot: 'bg-sky-400' } : { ring: 'border-rose-500/30 bg-rose-500/10', dot: 'bg-rose-400' }; @@ -77,9 +77,9 @@ export default function QualityScore(): React.JSX.Element { } label={External references} value="16" />
- +
- +
Orphan Detection} value="21" />
diff --git a/src/css/custom.css b/src/css/custom.css index c70f47d..6f96871 100644 --- a/src/css/custom.css +++ b/src/css/custom.css @@ -88,7 +88,7 @@ --ifm-font-color-base: #e4e4e7; --ifm-heading-color: #fafafa; --ifm-color-primary: #818cf8; - + background-color: #09090b; background-image: radial-gradient(circle at top, #1c2128 0%, #09090b 80%); background-repeat: no-repeat; diff --git a/tsconfig.json b/tsconfig.json index 321af0d..7288243 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -1,6 +1,3 @@ -// This file is not used by "docusaurus start/build" commands. -// It is here to improve your IDE experience (type-checking, autocompletion...), -// and can also run the package.json "typecheck" script manually. { "extends": "@docusaurus/tsconfig/tsconfig.json", "compilerOptions": { diff --git a/zenzic.toml b/zenzic.toml index 5423792..3704a1b 100644 --- a/zenzic.toml +++ b/zenzic.toml @@ -1,8 +1,12 @@ -# SPDX-FileCopyrightText: 2025 PythonWoods +# SPDX-FileCopyrightText: 2026 PythonWoods # SPDX-License-Identifier: Apache-2.0 docs_dir = "docs" +excluded_external_urls = [ + "https://docs.github.com/en/authentication/managing-commit-signature-verification/", +] + # --- PROTEZIONE DOGFOODING --- # The documentation explains placeholder patterns by example, so the checker # would produce false positives on every page that describes its own rules. @@ -27,4 +31,4 @@ strict = true engine = "docusaurus" base_url = "/" default_locale = "en" -locales = ["it"] \ No newline at end of file +locales = ["it"] From 847795c628f7d6fc60eea8f9ed0ab254006dfc70 Mon Sep 17 00:00:00 2001 From: PythonWoods Date: Sun, 19 Apr 2026 20:13:35 +0200 Subject: [PATCH 02/13] docs: synchronize v0.6.1 'Obsidian Glass' manuals (EN/IT) Comprehensive update to align documentation with the v0.6.1 stable release and the findings of the Guardians of Quality audit. Changes: - Engines Guide: Added technical notes on Docusaurus v3 versioning logic. - Engines Guide: Documented @site/ alias and absolute slug behavior. - Engines Guide: Explained Smart Collapsing (README and Folder-name patterns). - Commands Guide: Updated --offline flag descriptions for all check commands. - Bilingual Parity: Fully synchronized all changes in Italian (i18n). - Legal: Fixed REUSE compliance for tsconfig.json and SVG assets. All documentation now reflects the 'Structural Custodian' philosophy. --- docs/guides/engines.mdx | 53 ++++++++++++++++++- docs/usage/commands.mdx | 6 +-- .../current/guides/engines.mdx | 53 ++++++++++++++++++- .../current/usage/commands.mdx | 7 +-- 4 files changed, 111 insertions(+), 8 deletions(-) diff --git a/docs/guides/engines.mdx b/docs/guides/engines.mdx index 96aa990..b4d0dce 100644 --- a/docs/guides/engines.mdx +++ b/docs/guides/engines.mdx @@ -281,7 +281,14 @@ Zenzic supports Docusaurus **multi-version documentation** out of the box. It id 2. **Versioned content** — discovered under `versioned_docs/version-{version}/`. 3. **Versioned translations** — discovered under `i18n/{locale}/docusaurus-plugin-content-docs/version-{version}/`. -The Virtual Site Map automatically maps these paths to their correct canonical URLs (e.g., `/docs/1.0.0/intro/`), allowing Zenzic to validate links across versions without requiring a build. +The Virtual Site Map automatically maps these paths to their correct canonical URLs, following Docusaurus's official versioning rules: + +- **Latest version** (the first entry in `versions.json`) maps to the `routeBasePath` root — **no version label in the URL**. + - Example: `versioned_docs/version-1.1.0/hello.md` with `versions.json = ["1.1.0", "1.0.0"]` → `/docs/hello/`. +- **Older versions** retain their version label in the URL. + - Example: `versioned_docs/version-1.0.0/hello.md` → `/docs/1.0.0/hello/`. + +This matches Docusaurus's own behavior exactly, preventing false positive broken-link reports against latest-version pages. :::tip[Ghost Routing] Versioned routes are treated as **Ghost Routes**: they are always considered reachable because Docusaurus automatically generates navigation for versioned documentation trees. @@ -307,6 +314,50 @@ The adapter identifies `i18n/{locale}/docusaurus-plugin-content-docs/current/` a locale mirror root. Files under these paths are excluded from the orphan check — they inherit nav membership from the default-locale original. +### Frontmatter slug rules + +Docusaurus allows overriding the canonical URL of any page via the `slug:` frontmatter key. +Zenzic applies the same rules as Docusaurus itself: + +- **Absolute slug** (starts with `/`): always prepended with `routeBasePath`. + - `slug: /bonjour` + `routeBasePath: docs` → `/docs/bonjour/`. + - `slug: /bonjour` + `routeBasePath: ''` (docs at site root) → `/bonjour/`. +- **Relative slug** (no leading `/`): replaces the last path segment only. + - `slug: setup` in `guide/install.md` → `/docs/guide/setup/`. + +### Smart file collapsing + +Zenzic mirrors Docusaurus's `isCategoryIndex` logic: a file collapses into its parent +directory URL when its name (case-insensitive) is: + +- `index` — e.g. `guides/index.md` → `/docs/guides/` +- `readme` — e.g. `guides/README.md` → `/docs/guides/` +- The parent folder's name — e.g. `Guides/Guides.md` → `/docs/Guides/` + +This prevents Zenzic from reporting broken links when authors use any of these three +conventions to create category landing pages. + +### `@site/` alias resolution + +Docusaurus projects frequently use the `@site/` alias in links to reference files +relative to the project root: + +```markdown +[Architecture diagram](@site/static/img/arch.png) +[Source code](@site/docs/internals/architecture.mdx) +``` + +Zenzic resolves `@site/` to the repository root automatically. Links starting with +`@site/docs/` are resolved against the docs root; all other `@site/` paths are checked +against the repository root. This means Zenzic validates these links without triggering +false-positive **PathTraversal** errors. + +:::note +To enable full `@site/` resolution, set `repo_root` in your `zenzic.toml` +`[build_context]` section, or run `zenzic check` from the project root so Zenzic +can detect it automatically. +::: + ### MDX support Docusaurus uses MDX (`.mdx`) files natively. The adapter treats `.mdx` files identically diff --git a/docs/usage/commands.mdx b/docs/usage/commands.mdx index 9260e91..5364873 100644 --- a/docs/usage/commands.mdx +++ b/docs/usage/commands.mdx @@ -91,8 +91,8 @@ zenzic check all --quiet ### `--offline` `--offline` is available on `check all`, `check links`, and `check orphans`. It forces -all adapters (MkDocs and Zensical) to resolve URLs **without** `use_directory_urls`, -producing flat `.html` paths instead of clean directory-based slugs. +all adapters (MkDocs, Zensical, and Docusaurus) to resolve URLs **without** +`use_directory_urls`, producing flat `.html` paths instead of clean directory-based slugs. Use this flag when linting documentation that will be distributed as static files — for example, bundled onto a USB drive or served over an intranet without a web server. @@ -110,7 +110,7 @@ SENTINEL: [Offline Mode Active: forcing flat URL structure] ``` :::note[Engine parity] -The `--offline` flag has **identical behaviour** on both the MkDocs and Zensical adapters. +The `--offline` flag has **identical behaviour** on MkDocs, Zensical, and Docusaurus adapters. This ensures Zenzic remains a consistent Structural Custodian regardless of your build engine. ::: diff --git a/i18n/it/docusaurus-plugin-content-docs/current/guides/engines.mdx b/i18n/it/docusaurus-plugin-content-docs/current/guides/engines.mdx index 4f257d9..7372797 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/guides/engines.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/guides/engines.mdx @@ -287,7 +287,14 @@ Zenzic supporta nativamente la **documentazione multi-versione** di Docusaurus. 2. **Contenuto versionato** — scoperto sotto `versioned_docs/version-{version}/`. 3. **Traduzioni versionate** — scoperte sotto `i18n/{locale}/docusaurus-plugin-content-docs/version-{version}/`. -La Virtual Site Map mappa automaticamente questi percorsi ai rispettivi URL canonici (es. `/docs/1.0.0/intro/`), permettendo a Zenzic di validare i link tra le versioni senza richiedere una build. +La Virtual Site Map mappa automaticamente questi percorsi ai rispettivi URL canonici, seguendo le regole ufficiali di versionamento di Docusaurus: + +- **Versione latest** (la prima voce in `versions.json`) mappa sulla root della `routeBasePath` — **senza etichetta di versione nell'URL**. + - Esempio: `versioned_docs/version-1.1.0/hello.md` con `versions.json = ["1.1.0", "1.0.0"]` → `/docs/hello/`. +- **Versioni precedenti** conservano l'etichetta di versione nell'URL. + - Esempio: `versioned_docs/version-1.0.0/hello.md` → `/docs/1.0.0/hello/`. + +Questo rispecchia esattamente il comportamento di Docusaurus, prevenendo falsi positivi di link rotti sulle pagine della versione latest. :::tip[Ghost Routing] Le rotte versionate sono trattate come **Ghost Routes**: sono sempre considerate raggiungibili perché Docusaurus genera automaticamente la navigazione per gli alberi di documentazione versionati. @@ -313,6 +320,50 @@ L'adapter identifica `i18n/{locale}/docusaurus-plugin-content-docs/current/` com mirror locale. I file sotto questi percorsi vengono esclusi dal controllo orphan — ereditano l'appartenenza alla nav dall'originale nel locale predefinito. +### Regole frontmatter slug + +Docusaurus consente di sovrascrivere l'URL canonico di qualsiasi pagina tramite la chiave +frontmatter `slug:`. Zenzic applica le stesse regole di Docusaurus: + +- **Slug assoluto** (inizia con `/`): sempre preceduto dalla `routeBasePath`. + - `slug: /ciao` + `routeBasePath: docs` → `/docs/ciao/`. + - `slug: /ciao` + `routeBasePath: ''` (docs alla root del sito) → `/ciao/`. +- **Slug relativo** (senza `/` iniziale): sostituisce solo l'ultimo segmento del percorso. + - `slug: setup` in `guide/install.md` → `/docs/guide/setup/`. + +### Collasso intelligente dei file + +Zenzic rispecchia la logica `isCategoryIndex` di Docusaurus: un file collassa nell'URL +della directory genitore quando il suo nome (case-insensitive) è: + +- `index` — es. `guides/index.md` → `/docs/guides/` +- `readme` — es. `guides/README.md` → `/docs/guides/` +- Il nome della cartella genitore — es. `Guide/Guide.md` → `/docs/Guide/` + +Questo evita che Zenzic segnali link rotti quando gli autori usano una di queste tre +convenzioni per creare pagine di atterraggio di categoria. + +### Risoluzione alias `@site/` + +I progetti Docusaurus usano frequentemente l'alias `@site/` nei link per referenziare file +relativi alla root del progetto: + +```markdown +[Diagramma architettura](@site/static/img/arch.png) +[Codice sorgente](@site/docs/internals/architecture.mdx) +``` + +Zenzic risolve `@site/` automaticamente alla root del repository. I link che iniziano con +`@site/docs/` vengono risolti rispetto alla docs root; tutti gli altri percorsi `@site/` +vengono verificati rispetto alla root del repository. Questo significa che Zenzic valida +questi link senza generare falsi positivi di errore **PathTraversal**. + +:::note +Per abilitare la risoluzione completa di `@site/`, imposta `repo_root` nella sezione +`[build_context]` del tuo `zenzic.toml`, oppure esegui `zenzic check` dalla root del +progetto affinché Zenzic possa rilevarlo automaticamente. +::: + ### Supporto MDX Docusaurus usa file MDX (`.mdx`) nativamente. L'adapter tratta i file `.mdx` in modo diff --git a/i18n/it/docusaurus-plugin-content-docs/current/usage/commands.mdx b/i18n/it/docusaurus-plugin-content-docs/current/usage/commands.mdx index 0c0e268..3e430e2 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/usage/commands.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/usage/commands.mdx @@ -92,8 +92,9 @@ zenzic check all --quiet ### `--offline` `--offline` è disponibile su `check all`, `check links` e `check orphans`. Forza -tutti gli adapter (MkDocs e Zensical) a risolvere gli URL **senza** `use_directory_urls`, -producendo percorsi `.html` piatti invece di slug clean basati su directory. +tutti gli adapter (MkDocs, Zensical e Docusaurus) a risolvere gli URL **senza** +`use_directory_urls`, producendo percorsi `.html` piatti invece di slug clean basati +su directory. Usalo quando esegui il linting di documentazione distribuita come file statici — ad esempio su chiavetta USB o su rete intranet senza web server. @@ -111,7 +112,7 @@ SENTINEL: [Offline Mode Active: forcing flat URL structure] ``` :::note[Parità tra engine] -Il flag `--offline` ha un **comportamento identico** su entrambi gli adapter MkDocs e Zensical. +Il flag `--offline` ha un **comportamento identico** su MkDocs, Zensical e Docusaurus. Questo garantisce che Zenzic resti un Custode Strutturale coerente indipendentemente dal tuo motore di build. ::: From 9a1c041d1009032683d193beba1632bf47288553 Mon Sep 17 00:00:00 2001 From: PythonWoods-Dev Date: Mon, 20 Apr 2026 14:39:38 +0200 Subject: [PATCH 03/13] =?UTF-8?q?docs:=20add=20/docs/=20root=20landing=20p?= =?UTF-8?q?age=20=E2=80=94=20fix=20/docs/=20404=20[EN+IT]?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Creates docs/index.mdx as the Docusaurus-native index for /docs/, resolving the 404 reported in Google Search Console. Provides a navigation table linking to all major doc sections. Italian translation added at i18n/it/.../current/index.mdx. Fixed community/contribute link to use explicit relative path. --- docs/index.mdx | 42 +++++++++++++++++++ .../current/index.mdx | 42 +++++++++++++++++++ 2 files changed, 84 insertions(+) create mode 100644 docs/index.mdx create mode 100644 i18n/it/docusaurus-plugin-content-docs/current/index.mdx diff --git a/docs/index.mdx b/docs/index.mdx new file mode 100644 index 0000000..994a1f6 --- /dev/null +++ b/docs/index.mdx @@ -0,0 +1,42 @@ +--- +sidebar_position: 1 +sidebar_label: "Overview" +--- + +# Documentation Overview + +Welcome to the **Zenzic** documentation — the engineering-grade static analyzer for +Markdown-based documentation. + +Zenzic operates in the **Build-Aware Gap**: the critical moment between writing source +files and their transformation into a website. It builds a **Virtual Site Map (VSM)** +directly from raw Markdown source to validate links, detect orphans, scan for exposed +credentials, and enforce quality rules — without ever running the documentation build. + +## Where to start + +| Goal | Page | +| :--- | :--- | +| Install Zenzic and run your first check | [Introduction](./intro) | +| Understand which checks Zenzic runs | [Checks Reference](./guides/checks) | +| Configure `zenzic.toml` | [Configuration Reference](./guides/configuration-reference) | +| Integrate with GitHub Actions | [CI/CD Integration](./guides/ci-cd) | +| Explore the internal architecture | [Architecture Overview](./internals/architecture-overview) | +| Contribute to the project | [Contributing](./community/contribute/index.mdx) | + +## Quick start + +```bash +# Install +pip install zenzic + +# Initialise configuration (auto-detects engine) +zenzic init + +# Run all checks +zenzic check all +``` + +--- + +*"The Code is Law. The Documentation is Truth. The Sentinel is vigilant."* diff --git a/i18n/it/docusaurus-plugin-content-docs/current/index.mdx b/i18n/it/docusaurus-plugin-content-docs/current/index.mdx new file mode 100644 index 0000000..5cb5467 --- /dev/null +++ b/i18n/it/docusaurus-plugin-content-docs/current/index.mdx @@ -0,0 +1,42 @@ +--- +sidebar_position: 1 +sidebar_label: "Panoramica" +--- + +# Panoramica della documentazione + +Benvenuto nella documentazione di **Zenzic** — l'analizzatore statico di livello engineering +per documentazione basata su Markdown. + +Zenzic opera nel **Build-Aware Gap**: il momento critico tra la scrittura dei file sorgente e +la loro trasformazione in un sito web. Costruisce una **Virtual Site Map (VSM)** direttamente +dai sorgenti Markdown grezzi per validare link, rilevare orfani, scansionare credenziali esposte +e applicare regole di qualità — senza mai eseguire il build della documentazione. + +## Da dove iniziare + +| Obiettivo | Pagina | +| :--- | :--- | +| Installare Zenzic ed eseguire il primo controllo | [Introduzione](./intro) | +| Capire quali controlli esegue Zenzic | [Riferimento Controlli](./guides/checks) | +| Configurare `zenzic.toml` | [Riferimento Configurazione](./guides/configuration-reference) | +| Integrare con GitHub Actions | [Integrazione CI/CD](./guides/ci-cd) | +| Esplorare l'architettura interna | [Panoramica Architettura](./internals/architecture-overview) | +| Contribuire al progetto | [Guida ai Contributi](./community/contribute/index.mdx) | + +## Avvio rapido + +```bash +# Installazione +pip install zenzic + +# Inizializza la configurazione (rileva automaticamente l'engine) +zenzic init + +# Esegui tutti i controlli +zenzic check all +``` + +--- + +*"The Code is Law. The Documentation is Truth. The Sentinel is vigilant."* From a1a3bd3d92f2139e98024e2b3f8f548f0ab848a3 Mon Sep 17 00:00:00 2001 From: PythonWoods-Dev Date: Mon, 20 Apr 2026 14:39:58 +0200 Subject: [PATCH 04/13] docs(internals): document provides_index(), alias mapping in adapter contract [EN+IT] - writing-an-adapter.mdx: add provides_index() to Common Methods table and contract invariant #10 (sole method allowed to perform disk I/O) - architecture-overview.mdx: update BaseAdapter protocol block with provides_index(); add provides_index() bullet to key methods list; add 'Alias Mapping in InMemoryPathResolver' section (#alias-mapping) documenting @site/ virtual prefix resolution Italian translations updated in parallel. --- docs/internals/architecture-overview.mdx | 16 ++++++++++++++++ docs/internals/developers/writing-an-adapter.mdx | 8 ++++++++ .../current/internals/architecture-overview.mdx | 15 +++++++++++++++ .../internals/developers/writing-an-adapter.mdx | 8 ++++++++ 4 files changed, 47 insertions(+) diff --git a/docs/internals/architecture-overview.mdx b/docs/internals/architecture-overview.mdx index 37a7dea..c1619ff 100644 --- a/docs/internals/architecture-overview.mdx +++ b/docs/internals/architecture-overview.mdx @@ -232,12 +232,14 @@ class BaseAdapter(Protocol): def resolve_anchor(self, resolved_file, anchor, anchors_cache, docs_root) -> bool: ... def get_ignored_patterns(self) -> set[str]: ... def is_shadow_of_nav_page(self, rel: Path, nav_paths: frozenset[str]) -> bool: ... + def provides_index(self, directory_path: Path) -> bool: ... ``` Key methods: - **`has_engine_config()`** -- Returns `True` when a build-engine config was found. `VanillaAdapter` returns `False`. Callers use this to decide whether nav-based checks (orphan detection) can produce meaningful results. - **`get_route_info()`** -- The Metadata-Driven Routing API. Returns all routing metadata in a single call: canonical URL, route status, optional slug, route base path, and proxy flag. +- **`provides_index(directory_path)`** -- **Discovery-phase I/O hook.** Returns `True` when the engine will generate a landing page for the given directory. Called once per directory by `find_missing_directory_indices()` — never inside per-link or per-file hot loops. This is the only `BaseAdapter` method that may perform disk I/O (`Path.exists()`). - **`map_url()` / `classify_route()`** -- Legacy File-to-URL API, preserved for backward compatibility. Default implementations delegate to `get_route_info()`. ### `RouteMetadata` {#route-metadata} @@ -299,6 +301,20 @@ However, Zenzic's **link integrity** validation (broken links, absolute paths) r **Architectural invariant:** keep the filesystem hierarchy aligned with the intended URL hierarchy. If a file is moved to a new directory, let the URL follow naturally rather than using `slug` to pin the old URL. This ensures `../` links resolve identically in both the linter and the static-site generator. +### Alias Mapping in `InMemoryPathResolver` {#alias-mapping} + +The `InMemoryPathResolver` is not a simple file-lookup table. It implements an **Alias Mapping** layer that translates virtual path prefixes into physical filesystem paths before any link validation takes place. + +The resolver is initialised once during Phase 1 with a complete in-memory file map. At initialisation it also registers all known alias prefixes for the active adapter. Currently supported aliases: + +| Alias prefix | Resolves to | Engine | +| :--- | :--- | :--- | +| `@site/` | `repo_root/` | Docusaurus | + +When a link target uses `@site/static/img/logo.png`, the resolver strips the virtual prefix and remaps the path to `repo_root/static/img/logo.png` before checking for file existence. This prevents spurious `PATH_TRAVERSAL` errors that would otherwise fire for valid Docusaurus project-relative references. + +**Key property:** alias resolution happens entirely in memory. No disk I/O is performed; the resolver consults only the file index built during Phase 1. This preserves the Zero-I/O hot-path invariant (Core Law 1). + ### Engine Factory {#engine-factory} The `get_adapter()` factory uses entry-point discovery to find adapters: diff --git a/docs/internals/developers/writing-an-adapter.mdx b/docs/internals/developers/writing-an-adapter.mdx index c226a26..b6a3edf 100644 --- a/docs/internals/developers/writing-an-adapter.mdx +++ b/docs/internals/developers/writing-an-adapter.mdx @@ -52,6 +52,7 @@ to `get_route_info()`. | `get_ignored_patterns()` | Which filename globs should the orphan check skip? | | `get_nav_paths()` | Which `.md` paths are listed in this engine's nav config? | | `has_engine_config()` | Was a build-engine config file found on disk? (Controls orphan check activation.) | +| `provides_index(directory_path)` | Does this directory have an engine-provided landing page? (Controls `MISSING_DIRECTORY_INDEX` emission.) | --- @@ -290,6 +291,13 @@ incorrect results: 8. `resolve_anchor()` must never raise — return `False` on any failure. The `anchors_cache` argument is read-only; do not mutate it. 9. `has_engine_config()` must never raise — return `False` on any failure. +10. `provides_index(directory_path)` **is the only method permitted to do I/O**. + It is called once per directory during the discovery phase — never inside + per-link or per-file hot loops — so a single `Path.exists()` call is + acceptable. Return `True` if your engine will generate a landing page for + the directory (e.g. via `index.md`, `README.md`, or a dynamic config entry + like `_category_.json` with `"link": {"type": "generated-index"}`). Never + raise — return `False` on any I/O failure. --- diff --git a/i18n/it/docusaurus-plugin-content-docs/current/internals/architecture-overview.mdx b/i18n/it/docusaurus-plugin-content-docs/current/internals/architecture-overview.mdx index 069482a..5379179 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/internals/architecture-overview.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/internals/architecture-overview.mdx @@ -118,6 +118,7 @@ Gli adapter sono il meccanismo che permette a Zenzic di supportare diversi motor | `map_url(rel_path)` | Mappa un percorso file relativo al suo URL canonico | | `resolve_asset(path, docs_root)` | Risolve un asset con fallback i18n | | `resolve_anchor(file, anchor, cache, docs_root)` | Risolve un'ancora con fallback i18n | +| `provides_index(directory_path)` | **Hook I/O della fase di discovery.** Restituisce `True` se il motore genererà una landing page per questa directory. Unico metodo del protocollo che può eseguire I/O su disco (`Path.exists()`). | ### RouteMetadata @@ -171,6 +172,20 @@ Tuttavia, la validazione dell'**integrità dei link** di Zenzic (link rotti, per **Invariante architetturale:** mantieni la gerarchia del filesystem allineata alla gerarchia degli URL desiderata. Se un file viene spostato in una nuova directory, lascia che l'URL segua naturalmente piuttosto che usare `slug` per bloccare il vecchio URL. Questo garantisce che i link `../` si risolvano in modo identico sia nel linter che nel generatore di siti statici. +### Mapping degli Alias in `InMemoryPathResolver` {#alias-mapping} + +`InMemoryPathResolver` non è un semplice indice di file. Implementa uno strato di **Mapping degli Alias** che traduce prefissi di percorso virtuali in percorsi fisici del filesystem prima di qualsiasi validazione dei link. + +Il resolver viene inizializzato una volta durante la Fase 1 con una mappa completa dei file in memoria. All'inizializzazione registra anche tutti i prefissi alias noti per l'adapter attivo. Alias attualmente supportati: + +| Prefisso alias | Risolve in | Engine | +| :--- | :--- | :--- | +| `@site/` | `repo_root/` | Docusaurus | + +Quando il target di un link usa `@site/static/img/logo.png`, il resolver rimuove il prefisso virtuale e rimappa il percorso in `repo_root/static/img/logo.png` prima di verificare l'esistenza del file. Questo previene errori spuri `PATH_TRAVERSAL` che altrimenti si attiverebbero per riferimenti Docusaurus relativi al progetto perfettamente validi. + +**Proprietà chiave:** la risoluzione degli alias avviene interamente in memoria. Non viene eseguito alcun I/O su disco; il resolver consulta solo l'indice dei file costruito durante la Fase 1. Questo preserva l'invariante Zero-I/O nel percorso critico (Legge Core 1). + ### Factory degli engine ```mermaid diff --git a/i18n/it/docusaurus-plugin-content-docs/current/internals/developers/writing-an-adapter.mdx b/i18n/it/docusaurus-plugin-content-docs/current/internals/developers/writing-an-adapter.mdx index 67ae8d7..c310aa5 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/internals/developers/writing-an-adapter.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/internals/developers/writing-an-adapter.mdx @@ -52,6 +52,7 @@ delegano a `get_route_info()`. | `get_ignored_patterns()` | Quali glob di filename deve saltare il controllo orfani? | | `get_nav_paths()` | Quali percorsi `.md` sono dichiarati nella nav di questo motore? | | `has_engine_config()` | È stato trovato un file di config del motore? (Controlla l'attivazione del controllo orfani.) | +| `provides_index(directory_path)` | Questa directory ha una landing page fornita dall'engine? (Controlla l'emissione di `MISSING_DIRECTORY_INDEX`.) | --- @@ -290,6 +291,13 @@ Zenzic potrebbe produrre risultati errati: 8. `resolve_anchor()` non deve mai sollevare eccezioni — restituisci `False` in caso di errore. L'argomento `anchors_cache` è in sola lettura; non mutarlo. 9. `has_engine_config()` non deve mai sollevare eccezioni — restituisci `False` in caso di errore. +10. `provides_index(directory_path)` **è l'unico metodo che può eseguire I/O**. + Viene chiamato una volta per directory durante la fase di discovery — mai + all'interno dei loop critici per-link o per-file — quindi una singola chiamata + `Path.exists()` è accettabile. Restituisci `True` se il tuo engine genererà una + landing page per la directory (es. tramite `index.md`, `README.md`, o una voce + di configurazione dinamica come `_category_.json` con `"link": {"type": "generated-index"}`). Non + sollevare mai eccezioni — restituisci `False` in caso di errore I/O. --- From 3f79f52459eccf3e99c01b55be2288ac1f37366f Mon Sep 17 00:00:00 2001 From: PythonWoods-Dev Date: Mon, 20 Apr 2026 14:40:14 +0200 Subject: [PATCH 05/13] docs(internals): add Finding Codes reference page [EN+IT] MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit New docs/internals/findings-codes.mdx — authoritative index of all Zenzic finding codes with severity, exit code impact, and remediation guidance. Includes dedicated MISSING_DIRECTORY_INDEX section (#missing-directory-index) with engine-aware index detection table and remediation examples. IT: 'Integrità dell'\''Indice di Directory' IT translation at i18n/it/.../current/internals/findings-codes.mdx. --- docs/internals/findings-codes.mdx | 175 ++++++++++++++++++ .../current/internals/findings-codes.mdx | 175 ++++++++++++++++++ 2 files changed, 350 insertions(+) create mode 100644 docs/internals/findings-codes.mdx create mode 100644 i18n/it/docusaurus-plugin-content-docs/current/internals/findings-codes.mdx diff --git a/docs/internals/findings-codes.mdx b/docs/internals/findings-codes.mdx new file mode 100644 index 0000000..e39c7b8 --- /dev/null +++ b/docs/internals/findings-codes.mdx @@ -0,0 +1,175 @@ +--- +sidebar_position: 4 +sidebar_label: "Finding Codes" +description: "Complete reference for all Zenzic finding codes, their severity levels, exit code impact, and remediation guidance." +--- + +{/* SPDX-FileCopyrightText: 2026 PythonWoods */} +{/* SPDX-License-Identifier: Apache-2.0 */} + +# Finding Codes Reference + +Every issue detected by Zenzic is tagged with a **finding code** that identifies +its category. This page is the authoritative index of all codes, their severity +levels, and what they mean for your exit code. + +:::info[Severity vs. exit code] +Severity describes the nature of the issue; the exit code determines whether +`zenzic check` signals failure to the shell or CI system. + +| Severity | Exit code impact | +| :--- | :--- | +| `error` | Exit 1 (suppressible by `--exit-zero`) | +| `warning` | Exit 1 in `--strict` mode only | +| `info` | Never affects exit code — use `--show-info` to display | +| `security_breach` | Exit 2 — never suppressible | +| `security_incident` | Exit 3 — never suppressible | +::: + +--- + +## Link Checks + +| Code | Severity | CLI | Meaning | +| :--- | :---: | :--- | :--- | +| `FILE_NOT_FOUND` | error | `check links` | A relative link target does not exist on disk | +| `ANCHOR_NOT_FOUND` | error | `check links` | The `#heading-anchor` in a link does not exist in the target file | +| `EXTERNAL_BROKEN` | error | `check links --strict` | An HTTP HEAD/GET request to an external URL returned a non-2xx/3xx status | +| `CIRCULAR_LINK` | info | `check links` | The resolved link target is part of a detected link cycle | +| `PATH_TRAVERSAL` | error | `check links` | A link resolves outside the `docs/` directory | +| `PATH_TRAVERSAL_SUSPICIOUS` | security_incident | `check links` | A link resolves to a known OS system path (`/etc/`, `/root/`, etc.) — triggers **Exit 3 (Blood Sentinel)** | + +--- + +## Orphan Check + +| Code | Severity | CLI | Meaning | +| :--- | :---: | :--- | :--- | +| `ORPHAN` | warning | `check orphans` | A `.md` file exists on disk but is not listed in the site navigation | + +--- + +## Snippet Check + +| Code | Severity | CLI | Meaning | +| :--- | :---: | :--- | :--- | +| `SNIPPET` | error | `check snippets` | A fenced code block with a checkable language tag (`python`, `yaml`, `json`, `toml`) contains a syntax error | + +--- + +## Placeholder Check + +| Code | Severity | CLI | Meaning | +| :--- | :---: | :--- | :--- | +| `short-content` | warning | `check placeholders` | Page word count is below `placeholder_max_words` (default: 50) | +| `placeholder-text` | warning | `check placeholders` | Page contains a pattern from `placeholder_patterns` (e.g. `TODO`, `WIP`, `Draft`) | + +--- + +## Asset Check + +| Code | Severity | CLI | Meaning | +| :--- | :---: | :--- | :--- | +| `ASSET` | warning | `check assets` | An image or media file in `docs/` is not referenced by any `.md` page | + +--- + +## Reference Pipeline + +| Code | Severity | CLI | Meaning | +| :--- | :---: | :--- | :--- | +| `DANGLING_REF` | error | `check references` | A `[text][id]` usage references an ID that has no definition in the file | +| `DEAD_DEF` | warning | `check references` | A `[id]: url` definition exists but is never used in the file | +| `DUPLICATE_DEF` | warning | `check references` | The same reference ID is defined twice; the first definition wins (CommonMark §4.7) | +| `MISSING_ALT` | warning | `check references` | An image (`![](url)`) has a blank or absent alt-text attribute | + +--- + +## Shield (Credential Detection) + +Shield findings always produce **Exit 2**. They are never suppressible. + +| Code | Pattern family | Example prefix | +| :--- | :--- | :--- | +| `openai-api-key` | OpenAI API key | `sk-…` | +| `github-token` | GitHub personal / OAuth token | `gh[pousr]_…` | +| `aws-access-key` | AWS IAM access key ID | `AKIA…` | +| `stripe-live-key` | Stripe live secret key | `sk_live_…` | +| `slack-token` | Slack bot / user / app token | `xox[baprs]-…` | +| `google-api-key` | Google Cloud / Maps API key | `AIza…` | +| `private-key` | PEM private key header | `-----BEGIN … PRIVATE KEY-----` | +| `hex-encoded-payload` | Hex-encoded byte sequence | `\xNN\xNN\xNN…` (3 or more consecutive hex escapes) | +| `gitlab-pat` | GitLab Personal Access Token | `glpat-…` | + +--- + +## Directory Index Integrity {#missing-directory-index} + +| Code | Severity | CLI | Meaning | +| :--- | :---: | :--- | :--- | +| `MISSING_DIRECTORY_INDEX` | info | `check all --show-info` | A directory contains Markdown source files but no engine-provided landing page — the directory URL may return a 404 | + +### What triggers this finding? + +`MISSING_DIRECTORY_INDEX` is emitted when `find_missing_directory_indices()` discovers +a subdirectory under `docs/` that satisfies both conditions: + +1. **Contains at least one `.md` or `.mdx` source file** — the directory is part of + the live documentation. +2. **Does not provide an index page** as recognised by the active adapter's + `provides_index()` method. + +The check is **engine-aware**: each adapter knows what constitutes a directory +landing page for its build engine: + +| Engine | What counts as an index | +| :--- | :--- | +| Docusaurus | `index.md`, `index.mdx`, `README.md`, `README.mdx`, or `_category_.json` with `"link": {"type": "generated-index"}` | +| MkDocs | `index.md` or `README.md` | +| Zensical | `index.md` | +| Vanilla | `index.md` | + +### Why severity `info`? + +A missing directory index is not always a hard error. Some sites intentionally +omit a `docs/` root index, or use the build engine's default category page +rather than a hand-authored one. `info` severity means: + +- **Never blocks CI** — the finding does not contribute to Exit 1. +- **Never affects the quality score.** +- **Visible on demand** — use `--show-info` to see these signals during development. + +### How to fix + +Create an appropriate index file in the reported directory: + +```bash +# Docusaurus: an MDX index page at docs/my-section/index.mdx +touch docs/my-section/index.mdx + +# MkDocs / Zensical: a standard index +echo "# My Section" > docs/my-section/index.md +``` + +Alternatively, for Docusaurus, add a `_category_.json` with a generated index: + +```json +{ + "label": "My Section", + "position": 3, + "link": { + "type": "generated-index", + "description": "Overview of everything in this section." + } +} +``` + +--- + +## Rule Engine (Custom Rules) + +| Code | Severity | CLI | Meaning | +| :--- | :---: | :--- | :--- | +| User-defined rule ID (e.g. `NO_DRAFT`) | Configured in `[[custom_rules]]` | `check all` | A line matched a user-defined regex pattern | +| `Z009` | error | `check all` | A worker process exceeded the 30-second per-file timeout — likely caused by catastrophic backtracking in a `[[custom_rules]]` regex pattern | +| `RULE-ENGINE-ERROR` | error | `check all` | A worker process raised an unexpected exception | diff --git a/i18n/it/docusaurus-plugin-content-docs/current/internals/findings-codes.mdx b/i18n/it/docusaurus-plugin-content-docs/current/internals/findings-codes.mdx new file mode 100644 index 0000000..2f3bacc --- /dev/null +++ b/i18n/it/docusaurus-plugin-content-docs/current/internals/findings-codes.mdx @@ -0,0 +1,175 @@ +--- +sidebar_position: 4 +sidebar_label: "Codici di Finding" +description: "Riferimento completo per tutti i codici di finding di Zenzic, i livelli di severità, l'impatto sul codice di uscita e le indicazioni di rimedio." +--- + +{/* SPDX-FileCopyrightText: 2026 PythonWoods */} +{/* SPDX-License-Identifier: Apache-2.0 */} + +# Riferimento Codici di Finding + +Ogni problema rilevato da Zenzic è contrassegnato da un **codice di finding** che +ne identifica la categoria. Questa pagina è l'indice autorevole di tutti i codici, +i loro livelli di severità e l'impatto sul codice di uscita. + +:::info[Severità vs. codice di uscita] +La severità descrive la natura del problema; il codice di uscita determina se +`zenzic check` segnala un errore alla shell o al sistema CI. + +| Severità | Impatto sul codice di uscita | +| :--- | :--- | +| `error` | Uscita 1 (sopprimibile con `--exit-zero`) | +| `warning` | Uscita 1 solo in modalità `--strict` | +| `info` | Non influenza mai il codice di uscita — usa `--show-info` per visualizzarlo | +| `security_breach` | Uscita 2 — mai sopprimibile | +| `security_incident` | Uscita 3 — mai sopprimibile | +::: + +--- + +## Controllo Link + +| Codice | Severità | CLI | Significato | +| :--- | :---: | :--- | :--- | +| `FILE_NOT_FOUND` | error | `check links` | Il target di un link relativo non esiste su disco | +| `ANCHOR_NOT_FOUND` | error | `check links` | Il frammento `#heading-anchor` nel link non esiste nel file target | +| `EXTERNAL_BROKEN` | error | `check links --strict` | Una richiesta HTTP HEAD/GET a un URL esterno ha restituito uno stato non-2xx/3xx | +| `CIRCULAR_LINK` | info | `check links` | Il target risolto del link fa parte di un ciclo di link rilevato | +| `PATH_TRAVERSAL` | error | `check links` | Un link risolve al di fuori della directory `docs/` | +| `PATH_TRAVERSAL_SUSPICIOUS` | security_incident | `check links` | Un link risolve in un percorso di sistema OS noto (`/etc/`, `/root/`, ecc.) — attiva **Uscita 3 (Blood Sentinel)** | + +--- + +## Controllo Orfani + +| Codice | Severità | CLI | Significato | +| :--- | :---: | :--- | :--- | +| `ORPHAN` | warning | `check orphans` | Un file `.md` esiste su disco ma non è elencato nella navigazione del sito | + +--- + +## Controllo Snippet + +| Codice | Severità | CLI | Significato | +| :--- | :---: | :--- | :--- | +| `SNIPPET` | error | `check snippets` | Un blocco di codice delimitato con un linguaggio verificabile (`python`, `yaml`, `json`, `toml`) contiene un errore di sintassi | + +--- + +## Controllo Placeholder + +| Codice | Severità | CLI | Significato | +| :--- | :---: | :--- | :--- | +| `short-content` | warning | `check placeholders` | Il conteggio parole della pagina è inferiore a `placeholder_max_words` (default: 50) | +| `placeholder-text` | warning | `check placeholders` | La pagina contiene un pattern da `placeholder_patterns` (es. `TODO`, `WIP`, `Bozza`) | + +--- + +## Controllo Asset + +| Codice | Severità | CLI | Significato | +| :--- | :---: | :--- | :--- | +| `ASSET` | warning | `check assets` | Un file immagine o multimediale in `docs/` non è referenziato da nessuna pagina `.md` | + +--- + +## Pipeline di Riferimenti + +| Codice | Severità | CLI | Significato | +| :--- | :---: | :--- | :--- | +| `DANGLING_REF` | error | `check references` | Un uso `[testo][id]` referenzia un ID che non ha definizione nel file | +| `DEAD_DEF` | warning | `check references` | Una definizione `[id]: url` esiste ma non viene mai usata nel file | +| `DUPLICATE_DEF` | warning | `check references` | Lo stesso ID di riferimento è definito due volte; vince la prima definizione (CommonMark §4.7) | +| `MISSING_ALT` | warning | `check references` | Un'immagine (`![](url)`) ha un attributo alt-text vuoto o assente | + +--- + +## Shield (Rilevamento Credenziali) + +I finding Shield producono sempre **Uscita 2**. Non sono mai sopprimibili. + +| Codice | Famiglia di pattern | Prefisso esempio | +| :--- | :--- | :--- | +| `openai-api-key` | Chiave API OpenAI | `sk-…` | +| `github-token` | Token personale / OAuth GitHub | `gh[pousr]_…` | +| `aws-access-key` | ID chiave di accesso AWS IAM | `AKIA…` | +| `stripe-live-key` | Chiave segreta live Stripe | `sk_live_…` | +| `slack-token` | Token bot / user / app Slack | `xox[baprs]-…` | +| `google-api-key` | Chiave API Google Cloud / Maps | `AIza…` | +| `private-key` | Intestazione chiave privata PEM | `-----BEGIN … PRIVATE KEY-----` | +| `hex-encoded-payload` | Sequenza di byte in esadecimale | `\xNN\xNN\xNN…` (3 o più escape esadecimali consecutivi) | +| `gitlab-pat` | Personal Access Token GitLab | `glpat-…` | + +--- + +## Integrità dell'Indice di Directory {#missing-directory-index} + +| Codice | Severità | CLI | Significato | +| :--- | :---: | :--- | :--- | +| `MISSING_DIRECTORY_INDEX` | info | `check all --show-info` | Una directory contiene file Markdown sorgente ma nessuna landing page fornita dall'engine — l'URL della directory potrebbe restituire un 404 | + +### Cosa attiva questo finding? + +`MISSING_DIRECTORY_INDEX` viene emesso quando `find_missing_directory_indices()` +scopre una sottodirectory sotto `docs/` che soddisfa entrambe le condizioni: + +1. **Contiene almeno un file sorgente `.md` o `.mdx`** — la directory fa parte + della documentazione attiva. +2. **Non fornisce una pagina indice** come riconosciuto dal metodo `provides_index()` + dell'adapter attivo. + +Il controllo è **engine-aware**: ogni adapter conosce cosa costituisce una +landing page di directory per il suo motore di build: + +| Engine | Cosa conta come indice | +| :--- | :--- | +| Docusaurus | `index.md`, `index.mdx`, `README.md`, `README.mdx`, o `_category_.json` con `"link": {"type": "generated-index"}` | +| MkDocs | `index.md` o `README.md` | +| Zensical | `index.md` | +| Vanilla | `index.md` | + +### Perché severità `info`? + +Un indice di directory mancante non è sempre un errore bloccante. Alcuni siti +omettono intenzionalmente un indice root `docs/`, o usano la pagina di categoria +predefinita dell'engine piuttosto che una scritta a mano. La severità `info` significa: + +- **Non blocca mai la CI** — il finding non contribuisce all'Uscita 1. +- **Non influenza il punteggio di qualità.** +- **Visibile su richiesta** — usa `--show-info` per vedere questi segnali durante lo sviluppo. + +### Come risolvere + +Crea un file indice appropriato nella directory segnalata: + +```bash +# Docusaurus: una pagina MDX indice in docs/mia-sezione/index.mdx +touch docs/mia-sezione/index.mdx + +# MkDocs / Zensical: un indice standard +echo "# La Mia Sezione" > docs/mia-sezione/index.md +``` + +In alternativa, per Docusaurus, aggiungi un `_category_.json` con un indice generato: + +```json +{ + "label": "La Mia Sezione", + "position": 3, + "link": { + "type": "generated-index", + "description": "Panoramica di tutto ciò che si trova in questa sezione." + } +} +``` + +--- + +## Rule Engine (Regole Custom) + +| Codice | Severità | CLI | Significato | +| :--- | :---: | :--- | :--- | +| ID regola definito dall'utente (es. `NO_DRAFT`) | Configurata in `[[custom_rules]]` | `check all` | Una riga ha matched un pattern regex definito dall'utente | +| `Z009` | error | `check all` | Un processo worker ha superato il timeout di 30 secondi per file — probabilmente causato da backtracking catastrofico in un pattern regex `[[custom_rules]]` | +| `RULE-ENGINE-ERROR` | error | `check all` | Un processo worker ha sollevato un'eccezione inattesa | From 733c4b49f0be0b05aa0989ace1df5705c40999e5 Mon Sep 17 00:00:00 2001 From: PythonWoods-Dev Date: Mon, 20 Apr 2026 14:40:32 +0200 Subject: [PATCH 06/13] docs(internals): add find_missing_directory_indices to API reference Adds find_missing_directory_indices to the scanner module members list in docs/internals/reference/api.mdx. --- docs/internals/reference/api.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/internals/reference/api.mdx b/docs/internals/reference/api.mdx index c382db9..4ec1c6e 100644 --- a/docs/internals/reference/api.mdx +++ b/docs/internals/reference/api.mdx @@ -25,6 +25,7 @@ Filesystem scanning utilities: repo root discovery, orphan page detection, asset - find_orphans - find_placeholders - find_unused_assets + - find_missing_directory_indices - calculate_orphans - calculate_unused_assets - check_placeholder_content From 3e2b6e3eebc2aa52a198a1e346a50cd87ddbb7f1 Mon Sep 17 00:00:00 2001 From: PythonWoods-Dev Date: Mon, 20 Apr 2026 15:44:20 +0200 Subject: [PATCH 07/13] docs(stable): remove --pre; promote zenzic lab in install guide [EN+IT] - usage/index.mdx: replace tip box with Install->zenzic lab->check all flow - usage/index.mdx: strip --pre from all Tabs install snippets - guides/index.mdx: uvx --pre -> uvx in zero-config tip - guides/ci-cd.mdx: strip --pre from all GitHub Actions and GitLab CI snippets - .github/workflows/ci.yml: uvx --pre -> uvx in Zenzic audit step - All changes mirrored in i18n/it/ v0.6.1 'Obsidian Glass' is stable. zenzic lab is the recommended onboarding path. --- .github/workflows/ci.yml | 2 +- docs/guides/ci-cd.mdx | 14 ++++++------- docs/guides/index.mdx | 2 +- docs/usage/index.mdx | 21 +++++++++++-------- .../current/guides/ci-cd.mdx | 14 ++++++------- .../current/guides/index.mdx | 2 +- .../current/usage/index.mdx | 21 +++++++++++-------- 7 files changed, 41 insertions(+), 35 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 0837be0..31010ee 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -83,4 +83,4 @@ jobs: uses: astral-sh/setup-uv@v7 - name: Zenzic Documentation Audit - run: uvx --pre zenzic check all --engine docusaurus --strict + run: uvx zenzic check all --engine docusaurus --strict diff --git a/docs/guides/ci-cd.mdx b/docs/guides/ci-cd.mdx index 8ff66f8..b0431c4 100644 --- a/docs/guides/ci-cd.mdx +++ b/docs/guides/ci-cd.mdx @@ -116,10 +116,10 @@ jobs: - uses: actions/checkout@v6 - name: Lint documentation - run: uvx --pre zenzic check all --strict + run: uvx zenzic check all --strict - name: Check references and run Shield - run: uvx --pre zenzic check references + run: uvx zenzic check references ``` @@ -150,10 +150,10 @@ jobs: enable-cache: true - name: Lint documentation - run: uvx --pre zenzic check all --strict + run: uvx zenzic check all --strict - name: Check references and run Shield - run: uvx --pre zenzic check references + run: uvx zenzic check references ``` The `enable-cache: true` option caches the uv tool cache across runs, @@ -187,7 +187,7 @@ steps: - name: 🛡️ Run Zenzic Score id: zenzic_step run: | - uvx --pre zenzic score --save # threshold read from fail_under in zenzic.toml + uvx zenzic score --save # threshold read from fail_under in zenzic.toml SCORE=$(jq '.score' .zenzic-score.json) echo "SCORE=$SCORE" >> "$GITHUB_OUTPUT" @@ -226,8 +226,8 @@ steps: ```yaml - name: Detect score regression run: | - uvx --pre zenzic score --save # update snapshot - uvx --pre zenzic diff --threshold 5 # fail if score drops > 5 points + uvx zenzic score --save # update snapshot + uvx zenzic diff --threshold 5 # fail if score drops > 5 points ``` Combine with branch protection rules to block merges that degrade documentation quality. diff --git a/docs/guides/index.mdx b/docs/guides/index.mdx index bb9f1df..e50088b 100644 --- a/docs/guides/index.mdx +++ b/docs/guides/index.mdx @@ -13,7 +13,7 @@ Zenzic reads a single `zenzic.toml` file at the repository root. All fields are :::tip[Zero configuration] -Most projects need no `zenzic.toml` at all. Run `uvx --pre zenzic check all` — if it passes, +Most projects need no `zenzic.toml` at all. Run `uvx zenzic check all` — if it passes, you're done. Only add configuration when you need to customise specific behaviour. ::: diff --git a/docs/usage/index.mdx b/docs/usage/index.mdx index d58728a..5afaac9 100644 --- a/docs/usage/index.mdx +++ b/docs/usage/index.mdx @@ -29,10 +29,13 @@ The repository ships maintained fixtures that mirror the documented contracts: :::tip[Just want to run it now?] ```bash -uvx --pre zenzic check all +pip install zenzic +zenzic lab # explore all 9 built-in examples — zero setup +zenzic check all # protect your own documentation ``` -No installation required. `uvx` downloads and runs Zenzic in a throwaway environment. +Curious how Zenzic handles Docusaurus v3 versioning or the Zensical transparent proxy? +Launch `zenzic lab` and watch the Sentinel in action across every supported engine. ::: import { SummaryTerminal } from '@site/src/components/SentinelTerminal'; @@ -49,7 +52,7 @@ import { SummaryTerminal } from '@site/src/components/SentinelTerminal'; ```bash -uvx --pre zenzic check all +uvx zenzic check all ``` `uvx` resolves and runs Zenzic from PyPI in a throwaway environment. Nothing is installed on @@ -60,7 +63,7 @@ avoid pinning a dev dependency. ```bash -pip install --pre zenzic +pip install zenzic zenzic check all ``` @@ -76,7 +79,7 @@ your system Python clean. ```bash -uv tool install --pre zenzic +uv tool install zenzic zenzic check all ``` @@ -89,7 +92,7 @@ a virtual environment. ```bash python -m venv ~/.local/zenzic-env source ~/.local/zenzic-env/bin/activate # Windows: .venv\Scripts\activate -pip install --pre zenzic +pip install zenzic ``` Install into a dedicated virtual environment, then add the `bin/` directory to your `PATH`. @@ -103,7 +106,7 @@ Install into a dedicated virtual environment, then add the `bin/` directory to y ```bash -uv add --dev --pre zenzic +uv add --dev zenzic uv run zenzic check all ``` @@ -117,7 +120,7 @@ pipelines that install project dependencies before running checks. ```bash python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate -pip install --pre zenzic +pip install zenzic zenzic check all ``` @@ -134,7 +137,7 @@ This means you **do not need to install** MkDocs, Material for MkDocs, or any ot ```bash # Lint any MkDocs project — no extras needed -uvx --pre zenzic check all +uvx zenzic check all ``` :::note[Third-party engine adapters] diff --git a/i18n/it/docusaurus-plugin-content-docs/current/guides/ci-cd.mdx b/i18n/it/docusaurus-plugin-content-docs/current/guides/ci-cd.mdx index 30646ce..8ceb8aa 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/guides/ci-cd.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/guides/ci-cd.mdx @@ -110,10 +110,10 @@ jobs: - uses: actions/checkout@v6 - name: Lint documentazione - run: uvx --pre zenzic check all --strict + run: uvx zenzic check all --strict - name: Controllo riferimenti e Shield - run: uvx --pre zenzic check references + run: uvx zenzic check references ``` @@ -144,10 +144,10 @@ jobs: enable-cache: true - name: Lint documentazione - run: uvx --pre zenzic check all --strict + run: uvx zenzic check all --strict - name: Controllo riferimenti e Shield - run: uvx --pre zenzic check references + run: uvx zenzic check references ``` L'opzione `enable-cache: true` mantiene la cache degli strumenti uv tra @@ -181,7 +181,7 @@ steps: - name: 🛡️ Calcola Zenzic Score id: zenzic_step run: | - uvx --pre zenzic score --save # soglia letta da fail_under in zenzic.toml + uvx zenzic score --save # soglia letta da fail_under in zenzic.toml SCORE=$(jq '.score' .zenzic-score.json) echo "SCORE=$SCORE" >> "$GITHUB_OUTPUT" @@ -220,8 +220,8 @@ steps: ```yaml - name: Rileva regressione del punteggio run: | - uvx --pre zenzic score --save # aggiorna snapshot - uvx --pre zenzic diff --threshold 5 # fallisce se il punteggio scende > 5 punti + uvx zenzic score --save # aggiorna snapshot + uvx zenzic diff --threshold 5 # fallisce se il punteggio scende > 5 punti ``` Combina con le branch protection rules per bloccare i merge che degradano la qualità della documentazione. diff --git a/i18n/it/docusaurus-plugin-content-docs/current/guides/index.mdx b/i18n/it/docusaurus-plugin-content-docs/current/guides/index.mdx index ae0095a..93d8a6d 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/guides/index.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/guides/index.mdx @@ -15,7 +15,7 @@ opzionali — Zenzic funziona senza alcun file di configurazione. :::tip[Configurazione zero] La maggior parte dei progetti non ha bisogno di alcun `zenzic.toml`. Esegui -`uvx --pre zenzic check all` — se passa, hai finito. Aggiungi configurazione solo quando +`uvx zenzic check all` — se passa, hai finito. Aggiungi configurazione solo quando devi personalizzare un comportamento specifico. ::: diff --git a/i18n/it/docusaurus-plugin-content-docs/current/usage/index.mdx b/i18n/it/docusaurus-plugin-content-docs/current/usage/index.mdx index a48ad0e..f46570e 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/usage/index.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/usage/index.mdx @@ -29,10 +29,13 @@ Il repository include fixture mantenuti e allineati ai contratti documentati: :::tip[Vuoi eseguirlo subito?] ```bash -uvx --pre zenzic check all +pip install zenzic +zenzic lab # esplora tutti i 9 esempi inclusi — zero setup +zenzic check all # proteggi la tua documentazione ``` -Nessuna installazione richiesta. `uvx` scarica ed esegue Zenzic in un ambiente temporaneo. +Vuoi vedere come Zenzic gestisce Docusaurus v3 o il proxy di Zensical? +Lancia `zenzic lab` e guarda la Sentinel in azione su ogni engine supportato. ::: --- @@ -45,7 +48,7 @@ Nessuna installazione richiesta. `uvx` scarica ed esegue Zenzic in un ambiente t ```bash -uvx --pre zenzic check all +uvx zenzic check all ``` `uvx` risolve ed esegue Zenzic da PyPI in un ambiente temporaneo. Nulla viene installato sul @@ -56,7 +59,7 @@ fissare una dipendenza dev. ```bash -pip install --pre zenzic +pip install zenzic zenzic check all ``` @@ -72,7 +75,7 @@ mantenere pulito il Python di sistema. ```bash -uv tool install --pre zenzic +uv tool install zenzic zenzic check all ``` @@ -85,7 +88,7 @@ attivare un virtual environment. ```bash python -m venv ~/.local/zenzic-env source ~/.local/zenzic-env/bin/activate # Windows: .venv\Scripts\activate -pip install --pre zenzic +pip install zenzic ``` Installa in un virtual environment dedicato, poi aggiungi la directory `bin/` al `PATH`. @@ -99,7 +102,7 @@ Installa in un virtual environment dedicato, poi aggiungi la directory `bin/` al ```bash -uv add --dev --pre zenzic +uv add --dev zenzic uv run zenzic check all ``` @@ -113,7 +116,7 @@ prima di eseguire i controlli. ```bash python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate -pip install --pre zenzic +pip install zenzic zenzic check all ``` @@ -130,7 +133,7 @@ Questo significa che **non è necessario installare** MkDocs, Material for MkDoc ```bash # Fare il lint di qualsiasi progetto MkDocs — nessun extra necessario -uvx --pre zenzic check all +uvx zenzic check all ``` :::note[Adapter di terze parti] From e5e7a821304740e7f22d5421036c9895e411358a Mon Sep 17 00:00:00 2001 From: PythonWoods Date: Mon, 20 Apr 2026 20:29:24 +0200 Subject: [PATCH 08/13] docs: replace magic language with deterministic terms EN+IT [Direttiva 027] MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CEO Direttiva 027 'Precision over Magic' — apply to all doc pages. Replace 'auto-detects'/'rileva automaticamente' with precise language: EN (5 files): - docs/guides/engines.mdx: 'auto-detects' -> 'deterministically discovers the engine:' - docs/guides/adapters-config.mdx: '## Adapter auto-detection' -> '## Adapter discovery (file-driven)' 'automatically from' -> 'deterministically resolves' - docs/usage/index.mdx: 'auto-detects the documentation engine' -> 'identifies the documentation engine from its configuration files' - docs/index.mdx: '# (auto-detects engine)' -> '# (discovers engine from config files)' - docs/guides/core-settings.mdx: 'auto-detects all non-default locales from' -> 'reads all non-default locales from' IT (5 files — bilingual parity): - Corresponding changes in i18n/it/docusaurus-plugin-content-docs/current/ --- docs/guides/adapters-config.mdx | 4 ++-- docs/guides/core-settings.mdx | 2 +- docs/guides/engines.mdx | 2 +- docs/index.mdx | 2 +- docs/usage/index.mdx | 4 ++-- .../current/guides/adapters-config.mdx | 2 +- .../current/guides/core-settings.mdx | 2 +- .../docusaurus-plugin-content-docs/current/guides/engines.mdx | 2 +- i18n/it/docusaurus-plugin-content-docs/current/index.mdx | 2 +- .../it/docusaurus-plugin-content-docs/current/usage/index.mdx | 4 ++-- 10 files changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/guides/adapters-config.mdx b/docs/guides/adapters-config.mdx index 1bce197..f41e8f9 100644 --- a/docs/guides/adapters-config.mdx +++ b/docs/guides/adapters-config.mdx @@ -78,9 +78,9 @@ its own copy of every page. --- -## Adapter auto-detection +## Adapter discovery (file-driven) -Zenzic resolves the correct adapter automatically from `build_context.engine`: +Zenzic deterministically resolves the correct adapter from `build_context.engine`: | `build_context.engine` | Config file present | Adapter selected | | :--- | :--- | :--- | diff --git a/docs/guides/core-settings.mdx b/docs/guides/core-settings.mdx index 9fb362a..e0041c5 100644 --- a/docs/guides/core-settings.mdx +++ b/docs/guides/core-settings.mdx @@ -101,7 +101,7 @@ excluded_asset_dirs = ["overrides", "_theme"] Filename glob patterns excluded from the orphan check. This is an escape hatch for non-standard setups. **For projects using `mkdocs-i18n` with `docs_structure: suffix`**, no configuration is -needed — Zenzic auto-detects all non-default locales from `mkdocs.yml` and excludes the +needed — Zenzic reads all non-default locales from `mkdocs.yml` and excludes the corresponding `*.{locale}.md` files automatically. ```toml diff --git a/docs/guides/engines.mdx b/docs/guides/engines.mdx index b4d0dce..fe25169 100644 --- a/docs/guides/engines.mdx +++ b/docs/guides/engines.mdx @@ -56,7 +56,7 @@ The `[build_context]` section in `zenzic.toml` tells Zenzic which engine your pr engine = "mkdocs" # or "zensical" or "docusaurus" ``` -If `[build_context]` is absent entirely, Zenzic auto-detects: +If `[build_context]` is absent entirely, Zenzic deterministically discovers the engine: - `mkdocs.yml` present → `MkDocsAdapter` - `docusaurus.config.ts` (or `.js`) present → `DocusaurusAdapter` diff --git a/docs/index.mdx b/docs/index.mdx index 994a1f6..79dbc74 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -30,7 +30,7 @@ credentials, and enforce quality rules — without ever running the documentatio # Install pip install zenzic -# Initialise configuration (auto-detects engine) +# Initialise configuration (discovers engine from config files) zenzic init # Run all checks diff --git a/docs/usage/index.mdx b/docs/usage/index.mdx index 5afaac9..66d4651 100644 --- a/docs/usage/index.mdx +++ b/docs/usage/index.mdx @@ -154,8 +154,8 @@ The standard workflow for adopting Zenzic in a project: ### 1. Init — scaffold a configuration file {#init} -Bootstrap a `zenzic.toml` with a single command. Zenzic auto-detects the documentation engine and -pre-populates `[build_context]` accordingly: +Bootstrap a `zenzic.toml` with a single command. Zenzic identifies the documentation engine +from its configuration files and pre-populates `[build_context]` accordingly: ```bash zenzic init diff --git a/i18n/it/docusaurus-plugin-content-docs/current/guides/adapters-config.mdx b/i18n/it/docusaurus-plugin-content-docs/current/guides/adapters-config.mdx index 90ab86b..d19da6b 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/guides/adapters-config.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/guides/adapters-config.mdx @@ -70,7 +70,7 @@ una pagina tradotta a una pagina che esiste solo nel locale di default viene sop --- -## Auto-rilevamento adapter +## Scoperta adapter (file-driven) | `build_context.engine` | File di configurazione presente | Adapter selezionato | | :--- | :--- | :--- | diff --git a/i18n/it/docusaurus-plugin-content-docs/current/guides/core-settings.mdx b/i18n/it/docusaurus-plugin-content-docs/current/guides/core-settings.mdx index f4cc15e..01311ab 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/guides/core-settings.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/guides/core-settings.mdx @@ -101,7 +101,7 @@ excluded_asset_dirs = ["overrides", "_theme"] Pattern glob sui nomi dei file esclusi dal controllo orfani. Questa è una via di fuga per setup non standard. **Per i progetti che usano `mkdocs-i18n` con `docs_structure: suffix`**, non è -necessaria alcuna configurazione — Zenzic rileva automaticamente tutti i locale non-default da +necessaria alcuna configurazione — Zenzic legge tutti i locale non-default da `mkdocs.yml` ed esclude automaticamente i file `*.{locale}.md` corrispondenti. ```toml diff --git a/i18n/it/docusaurus-plugin-content-docs/current/guides/engines.mdx b/i18n/it/docusaurus-plugin-content-docs/current/guides/engines.mdx index 7372797..51ac6aa 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/guides/engines.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/guides/engines.mdx @@ -60,7 +60,7 @@ progetto: engine = "mkdocs" # oppure "zensical" o "docusaurus" ``` -Se `[build_context]` è assente, Zenzic rileva automaticamente: +Se `[build_context]` è assente, Zenzic individua deterministicamente il motore: - `mkdocs.yml` presente → `MkDocsAdapter` - `docusaurus.config.ts` (o `.js`) presente → `DocusaurusAdapter` diff --git a/i18n/it/docusaurus-plugin-content-docs/current/index.mdx b/i18n/it/docusaurus-plugin-content-docs/current/index.mdx index 5cb5467..d38f2ab 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/index.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/index.mdx @@ -30,7 +30,7 @@ e applicare regole di qualità — senza mai eseguire il build della documentazi # Installazione pip install zenzic -# Inizializza la configurazione (rileva automaticamente l'engine) +# Inizializza la configurazione (individua l'engine dai file di config) zenzic init # Esegui tutti i controlli diff --git a/i18n/it/docusaurus-plugin-content-docs/current/usage/index.mdx b/i18n/it/docusaurus-plugin-content-docs/current/usage/index.mdx index f46570e..f7510ae 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/usage/index.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/usage/index.mdx @@ -150,8 +150,8 @@ Il workflow standard per adottare Zenzic in un progetto: ### 1. Init — scaffolding del file di configurazione {#init} -Crea un `zenzic.toml` con un singolo comando. Zenzic rileva automaticamente il motore di -documentazione e preimposta `[build_context]` di conseguenza: +Crea un `zenzic.toml` con un singolo comando. Zenzic identifica il motore di +documentazione dai file di configurazione presenti e preimposta `[build_context]` di conseguenza: ```bash zenzic init From 7d8d5137279932e97a01da97bc097496f98a82e1 Mon Sep 17 00:00:00 2001 From: PythonWoods Date: Mon, 20 Apr 2026 21:39:37 +0200 Subject: [PATCH 09/13] =?UTF-8?q?docs(arch):=20Di=C3=A1taxis=20restructuri?= =?UTF-8?q?ng=20+=20Unified=20Gateway=20=E2=80=94=20Obsidian=20Di=C3=A1tax?= =?UTF-8?q?is=20Phase=201+2=20[EN+IT]?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Ghost Shift: 29 EN + 29 IT files moved to Tutorials / How-to / Reference / Explanation quadrants (git history preserved as renames) - Developer sub-hierarchy relocated from internals/ → community/developers/ with nested Diátaxis sub-quadrants (tutorials/, how-to/, reference/, explanation/) - All internal cross-references healed in EN and IT (links, reference definitions, table hrefs) - sidebars.ts: switched to type:autogenerated — eliminates orphan ID risk on future moves - _category_.json: unique translation keys added to developer sub-categories to resolve Docusaurus duplicate-key conflict - Hero button: /docs/intro → /docs/ (D034 Unified Gateway) - docs/index.mdx: sidebar_position 0, table links updated to new paths - zenzic.toml: CORE SETTINGS / EXTERNAL VALIDATION / PROTEZIONE DOGFOODING / GESTIONE ASSET / ENGINE CONTEXT sections with inline reference comments - Build: SUCCESS (EN + IT, onBrokenLinks:throw) --- docs/community/brand-kit.mdx | 2 +- docs/community/developers/_category_.json | 3 + .../developers/explanation/_category_.json | 4 + .../developers/explanation/adr-discovery.mdx} | 0 .../explanation/architecture-gaps.mdx} | 0 .../developers/how-to/_category_.json | 4 + .../developers/how-to/implement-adapter.mdx} | 6 +- .../developers/how-to/write-plugin.mdx} | 6 +- .../developers/index.mdx | 6 +- .../developers/reference/_category_.json | 4 + .../developers/reference/adapter-api.mdx} | 0 .../developers/reference/sentinel-style.mdx} | 2 +- .../developers/tutorials/_category_.json | 4 + .../tutorials/adapter-examples.mdx} | 0 docs/community/faqs.mdx | 4 +- docs/community/index.mdx | 2 +- docs/ecosystem/_category_.json | 8 -- docs/examples/_category_.json | 8 -- docs/explanation/_category_.json | 7 ++ .../architecture.mdx} | 4 +- docs/{guides => explanation}/discovery.mdx | 0 .../ecosystem.mdx} | 6 +- .../safe-harbor.mdx} | 0 docs/guides/_category_.json | 9 --- docs/how-to/_category_.json | 7 ++ .../badges.mdx => how-to/add-badges.mdx} | 4 +- .../add-custom-rules.mdx} | 2 +- .../advanced-options.mdx} | 2 +- .../configure-adapter.mdx} | 2 +- .../ci-cd.mdx => how-to/configure-ci-cd.mdx} | 2 +- docs/{usage/index.mdx => how-to/install.mdx} | 10 +-- .../migrate-engines.mdx} | 2 +- docs/index.mdx | 12 +-- docs/internals/_category_.json | 8 -- docs/internals/adr/_category_.json | 8 -- docs/internals/developers/_category_.json | 8 -- docs/internals/reference/_category_.json | 8 -- docs/internals/security/_category_.json | 8 -- docs/reference/_category_.json | 4 + docs/{guides => reference}/checks.mdx | 0 .../{usage/commands.mdx => reference/cli.mdx} | 4 +- .../configuration-reference.mdx | 0 .../configuration.mdx} | 0 docs/{guides => reference}/engines.mdx | 2 +- .../finding-codes.mdx} | 0 docs/{guides => reference}/glossary.mdx | 6 +- docs/{guides => reference}/index.mdx | 6 +- docs/tutorials/_category_.json | 7 ++ .../overview.mdx => tutorials/examples.mdx} | 6 +- docs/{intro.mdx => tutorials/first-audit.mdx} | 2 +- docs/usage/_category_.json | 8 -- .../current/community/brand-kit.mdx | 2 +- .../community/developers/_category_.json | 3 + .../developers/explanation/_category_.json | 4 + .../developers/explanation/adr-discovery.mdx} | 0 .../explanation/architecture-gaps.mdx} | 0 .../developers/how-to/_category_.json | 4 + .../developers/how-to/implement-adapter.mdx} | 6 +- .../developers/how-to/write-plugin.mdx} | 6 +- .../developers/index.mdx | 6 +- .../developers/reference/_category_.json | 4 + .../developers/reference/adapter-api.mdx} | 0 .../developers/reference/sentinel-style.mdx} | 2 +- .../developers/tutorials/_category_.json | 4 + .../tutorials/adapter-examples.mdx} | 0 .../current/community/faqs.mdx | 4 +- .../current/community/index.mdx | 2 +- .../current/ecosystem/_category_.json | 8 -- .../current/examples/_category_.json | 8 -- .../current/explanation/_category_.json | 7 ++ .../architecture.mdx} | 4 +- .../{guides => explanation}/discovery.mdx | 0 .../ecosystem.mdx} | 6 +- .../safe-harbor.mdx} | 0 .../current/guides/_category_.json | 9 --- .../current/how-to/_category_.json | 7 ++ .../badges.mdx => how-to/add-badges.mdx} | 4 +- .../add-custom-rules.mdx} | 2 +- .../advanced-options.mdx} | 2 +- .../configure-adapter.mdx} | 2 +- .../ci-cd.mdx => how-to/configure-ci-cd.mdx} | 2 +- .../{usage/index.mdx => how-to/install.mdx} | 8 +- .../migrate-engines.mdx} | 2 +- .../current/index.mdx | 10 +-- .../current/internals/_category_.json | 8 -- .../current/internals/adr/_category_.json | 8 -- .../internals/developers/_category_.json | 8 -- .../internals/reference/_category_.json | 8 -- .../internals/security/_category_.json | 8 -- .../current/reference/_category_.json | 4 + .../current/{guides => reference}/checks.mdx | 0 .../{usage/commands.mdx => reference/cli.mdx} | 4 +- .../configuration-reference.mdx | 0 .../configuration.mdx} | 0 .../current/{guides => reference}/engines.mdx | 2 +- .../finding-codes.mdx} | 0 .../{guides => reference}/glossary.mdx | 6 +- .../current/{guides => reference}/index.mdx | 6 +- .../current/tutorials/_category_.json | 7 ++ .../overview.mdx => tutorials/examples.mdx} | 6 +- .../{intro.mdx => tutorials/first-audit.mdx} | 2 +- .../current/usage/_category_.json | 8 -- sidebars.ts | 78 +------------------ src/components/Homepage/Hero.tsx | 2 +- zenzic.toml | 24 +++--- 105 files changed, 203 insertions(+), 331 deletions(-) create mode 100644 docs/community/developers/_category_.json create mode 100644 docs/community/developers/explanation/_category_.json rename docs/{internals/adr/003-discovery-logic.mdx => community/developers/explanation/adr-discovery.mdx} (100%) rename docs/{internals/arch_gaps.mdx => community/developers/explanation/architecture-gaps.mdx} (100%) create mode 100644 docs/community/developers/how-to/_category_.json rename docs/{internals/developers/writing-an-adapter.mdx => community/developers/how-to/implement-adapter.mdx} (97%) rename docs/{internals/developers/plugins.mdx => community/developers/how-to/write-plugin.mdx} (97%) rename docs/{internals => community}/developers/index.mdx (92%) create mode 100644 docs/community/developers/reference/_category_.json rename docs/{internals/reference/api.mdx => community/developers/reference/adapter-api.mdx} (100%) rename docs/{internals/sentinel-style-guide.mdx => community/developers/reference/sentinel-style.mdx} (98%) create mode 100644 docs/community/developers/tutorials/_category_.json rename docs/{internals/developers/examples.mdx => community/developers/tutorials/adapter-examples.mdx} (100%) delete mode 100644 docs/ecosystem/_category_.json delete mode 100644 docs/examples/_category_.json create mode 100644 docs/explanation/_category_.json rename docs/{internals/architecture-overview.mdx => explanation/architecture.mdx} (99%) rename docs/{guides => explanation}/discovery.mdx (100%) rename docs/{ecosystem/overview.mdx => explanation/ecosystem.mdx} (93%) rename docs/{philosophy.mdx => explanation/safe-harbor.mdx} (100%) delete mode 100644 docs/guides/_category_.json create mode 100644 docs/how-to/_category_.json rename docs/{usage/badges.mdx => how-to/add-badges.mdx} (96%) rename docs/{guides/custom-rules-dsl.mdx => how-to/add-custom-rules.mdx} (98%) rename docs/{usage/advanced.mdx => how-to/advanced-options.mdx} (99%) rename docs/{guides/adapters-config.mdx => how-to/configure-adapter.mdx} (98%) rename docs/{guides/ci-cd.mdx => how-to/configure-ci-cd.mdx} (99%) rename docs/{usage/index.mdx => how-to/install.mdx} (95%) rename docs/{guides/migration.mdx => how-to/migrate-engines.mdx} (99%) delete mode 100644 docs/internals/_category_.json delete mode 100644 docs/internals/adr/_category_.json delete mode 100644 docs/internals/developers/_category_.json delete mode 100644 docs/internals/reference/_category_.json delete mode 100644 docs/internals/security/_category_.json create mode 100644 docs/reference/_category_.json rename docs/{guides => reference}/checks.mdx (100%) rename docs/{usage/commands.mdx => reference/cli.mdx} (98%) rename docs/{guides => reference}/configuration-reference.mdx (100%) rename docs/{guides/core-settings.mdx => reference/configuration.mdx} (100%) rename docs/{guides => reference}/engines.mdx (99%) rename docs/{internals/findings-codes.mdx => reference/finding-codes.mdx} (100%) rename docs/{guides => reference}/glossary.mdx (97%) rename docs/{guides => reference}/index.mdx (93%) create mode 100644 docs/tutorials/_category_.json rename docs/{examples/overview.mdx => tutorials/examples.mdx} (96%) rename docs/{intro.mdx => tutorials/first-audit.mdx} (97%) delete mode 100644 docs/usage/_category_.json create mode 100644 i18n/it/docusaurus-plugin-content-docs/current/community/developers/_category_.json create mode 100644 i18n/it/docusaurus-plugin-content-docs/current/community/developers/explanation/_category_.json rename i18n/it/docusaurus-plugin-content-docs/current/{internals/adr/003-discovery-logic.mdx => community/developers/explanation/adr-discovery.mdx} (100%) rename i18n/it/docusaurus-plugin-content-docs/current/{internals/arch_gaps.mdx => community/developers/explanation/architecture-gaps.mdx} (100%) create mode 100644 i18n/it/docusaurus-plugin-content-docs/current/community/developers/how-to/_category_.json rename i18n/it/docusaurus-plugin-content-docs/current/{internals/developers/writing-an-adapter.mdx => community/developers/how-to/implement-adapter.mdx} (98%) rename i18n/it/docusaurus-plugin-content-docs/current/{internals/developers/plugins.mdx => community/developers/how-to/write-plugin.mdx} (98%) rename i18n/it/docusaurus-plugin-content-docs/current/{internals => community}/developers/index.mdx (92%) create mode 100644 i18n/it/docusaurus-plugin-content-docs/current/community/developers/reference/_category_.json rename i18n/it/docusaurus-plugin-content-docs/current/{internals/reference/api.mdx => community/developers/reference/adapter-api.mdx} (100%) rename i18n/it/docusaurus-plugin-content-docs/current/{internals/sentinel-style-guide.mdx => community/developers/reference/sentinel-style.mdx} (98%) create mode 100644 i18n/it/docusaurus-plugin-content-docs/current/community/developers/tutorials/_category_.json rename i18n/it/docusaurus-plugin-content-docs/current/{internals/developers/examples.mdx => community/developers/tutorials/adapter-examples.mdx} (100%) delete mode 100644 i18n/it/docusaurus-plugin-content-docs/current/ecosystem/_category_.json delete mode 100644 i18n/it/docusaurus-plugin-content-docs/current/examples/_category_.json create mode 100644 i18n/it/docusaurus-plugin-content-docs/current/explanation/_category_.json rename i18n/it/docusaurus-plugin-content-docs/current/{internals/architecture-overview.mdx => explanation/architecture.mdx} (99%) rename i18n/it/docusaurus-plugin-content-docs/current/{guides => explanation}/discovery.mdx (100%) rename i18n/it/docusaurus-plugin-content-docs/current/{ecosystem/overview.mdx => explanation/ecosystem.mdx} (93%) rename i18n/it/docusaurus-plugin-content-docs/current/{philosophy.mdx => explanation/safe-harbor.mdx} (100%) delete mode 100644 i18n/it/docusaurus-plugin-content-docs/current/guides/_category_.json create mode 100644 i18n/it/docusaurus-plugin-content-docs/current/how-to/_category_.json rename i18n/it/docusaurus-plugin-content-docs/current/{usage/badges.mdx => how-to/add-badges.mdx} (98%) rename i18n/it/docusaurus-plugin-content-docs/current/{guides/custom-rules-dsl.mdx => how-to/add-custom-rules.mdx} (98%) rename i18n/it/docusaurus-plugin-content-docs/current/{usage/advanced.mdx => how-to/advanced-options.mdx} (99%) rename i18n/it/docusaurus-plugin-content-docs/current/{guides/adapters-config.mdx => how-to/configure-adapter.mdx} (98%) rename i18n/it/docusaurus-plugin-content-docs/current/{guides/ci-cd.mdx => how-to/configure-ci-cd.mdx} (99%) rename i18n/it/docusaurus-plugin-content-docs/current/{usage/index.mdx => how-to/install.mdx} (95%) rename i18n/it/docusaurus-plugin-content-docs/current/{guides/migration.mdx => how-to/migrate-engines.mdx} (99%) delete mode 100644 i18n/it/docusaurus-plugin-content-docs/current/internals/_category_.json delete mode 100644 i18n/it/docusaurus-plugin-content-docs/current/internals/adr/_category_.json delete mode 100644 i18n/it/docusaurus-plugin-content-docs/current/internals/developers/_category_.json delete mode 100644 i18n/it/docusaurus-plugin-content-docs/current/internals/reference/_category_.json delete mode 100644 i18n/it/docusaurus-plugin-content-docs/current/internals/security/_category_.json create mode 100644 i18n/it/docusaurus-plugin-content-docs/current/reference/_category_.json rename i18n/it/docusaurus-plugin-content-docs/current/{guides => reference}/checks.mdx (100%) rename i18n/it/docusaurus-plugin-content-docs/current/{usage/commands.mdx => reference/cli.mdx} (98%) rename i18n/it/docusaurus-plugin-content-docs/current/{guides => reference}/configuration-reference.mdx (100%) rename i18n/it/docusaurus-plugin-content-docs/current/{guides/core-settings.mdx => reference/configuration.mdx} (100%) rename i18n/it/docusaurus-plugin-content-docs/current/{guides => reference}/engines.mdx (99%) rename i18n/it/docusaurus-plugin-content-docs/current/{internals/findings-codes.mdx => reference/finding-codes.mdx} (100%) rename i18n/it/docusaurus-plugin-content-docs/current/{guides => reference}/glossary.mdx (96%) rename i18n/it/docusaurus-plugin-content-docs/current/{guides => reference}/index.mdx (93%) create mode 100644 i18n/it/docusaurus-plugin-content-docs/current/tutorials/_category_.json rename i18n/it/docusaurus-plugin-content-docs/current/{examples/overview.mdx => tutorials/examples.mdx} (96%) rename i18n/it/docusaurus-plugin-content-docs/current/{intro.mdx => tutorials/first-audit.mdx} (96%) delete mode 100644 i18n/it/docusaurus-plugin-content-docs/current/usage/_category_.json diff --git a/docs/community/brand-kit.mdx b/docs/community/brand-kit.mdx index 3a04e6a..2c4590d 100644 --- a/docs/community/brand-kit.mdx +++ b/docs/community/brand-kit.mdx @@ -52,7 +52,7 @@ that cannot reach `img.shields.io`: | Shield | ![Zenzic Shield](../assets/brand/svg/zenzic-badge-shield.svg) | Binary gate: passing / failing | | Score | ![Zenzic Score](../assets/brand/svg/zenzic-badge-score.svg) | Quality metric: 0–100 | -For dynamic Shields.io variants and CI/CD wiring, see the [Badges guide](../usage/badges.mdx). +For dynamic Shields.io variants and CI/CD wiring, see the [Badges guide](../how-to/add-badges.mdx). ## Download diff --git a/docs/community/developers/_category_.json b/docs/community/developers/_category_.json new file mode 100644 index 0000000..8de262b --- /dev/null +++ b/docs/community/developers/_category_.json @@ -0,0 +1,3 @@ +{ + "label": "Developer Guide" +} diff --git a/docs/community/developers/explanation/_category_.json b/docs/community/developers/explanation/_category_.json new file mode 100644 index 0000000..74c2dd8 --- /dev/null +++ b/docs/community/developers/explanation/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Explanation", + "key": "dev-explanation" +} diff --git a/docs/internals/adr/003-discovery-logic.mdx b/docs/community/developers/explanation/adr-discovery.mdx similarity index 100% rename from docs/internals/adr/003-discovery-logic.mdx rename to docs/community/developers/explanation/adr-discovery.mdx diff --git a/docs/internals/arch_gaps.mdx b/docs/community/developers/explanation/architecture-gaps.mdx similarity index 100% rename from docs/internals/arch_gaps.mdx rename to docs/community/developers/explanation/architecture-gaps.mdx diff --git a/docs/community/developers/how-to/_category_.json b/docs/community/developers/how-to/_category_.json new file mode 100644 index 0000000..3c01162 --- /dev/null +++ b/docs/community/developers/how-to/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "How-to", + "key": "dev-how-to" +} diff --git a/docs/internals/developers/writing-an-adapter.mdx b/docs/community/developers/how-to/implement-adapter.mdx similarity index 97% rename from docs/internals/developers/writing-an-adapter.mdx rename to docs/community/developers/how-to/implement-adapter.mdx index b6a3edf..67904a6 100644 --- a/docs/internals/developers/writing-an-adapter.mdx +++ b/docs/community/developers/how-to/implement-adapter.mdx @@ -329,11 +329,11 @@ def test_nav_paths_relative() -> None: Connect adapter code to deployment truth: 1. Register engine identity in project configuration via `[build_context] engine` - (see [Adapters & Engine Configuration](../../guides/adapters-config.mdx)). + (see [Adapters & Engine Configuration](../../../how-to/configure-adapter.mdx)). 2. Validate adapter behavior under strict Sentinel policy: `zenzic check all --engine myengine --strict`. - For run controls, see [CLI Commands: Global flags](../../usage/commands.mdx#global-flags). + For run controls, see [CLI Commands: Global flags](../../../reference/cli.mdx#global-flags). 3. If your engine generates synthetic locale routes, explicitly map Ghost Route expectations against the VSM reference: - [Checks Reference — VSM](../../guides/checks#vsm-how-it-works). + [Checks Reference — VSM](../../../reference/checks#vsm-how-it-works). ::: diff --git a/docs/internals/developers/plugins.mdx b/docs/community/developers/how-to/write-plugin.mdx similarity index 97% rename from docs/internals/developers/plugins.mdx rename to docs/community/developers/how-to/write-plugin.mdx index 6d14ab7..2327f63 100644 --- a/docs/internals/developers/plugins.mdx +++ b/docs/community/developers/how-to/write-plugin.mdx @@ -297,10 +297,10 @@ refuses to start. Fix the rule before running Zenzic. 2. Validate the rule under strict pipeline semantics: `zenzic check all --strict`. For run-time policy controls, see - [CLI Commands: Global flags](../../usage/commands.mdx#global-flags). + [CLI Commands: Global flags](../../../reference/cli.mdx#global-flags). 3. If your rule is nav-aware, map expected Ghost Route behavior against the VSM model: - [Checks Reference — VSM](../../guides/checks#vsm-how-it-works). + [Checks Reference — VSM](../../../reference/checks#vsm-how-it-works). ::: [ep]: https://packaging.python.org/en/latest/guides/creating-and-discovering-plugins/#using-package-metadata -[api-baserule]: ../reference/api.mdx +[api-baserule]: ../reference/adapter-api.mdx diff --git a/docs/internals/developers/index.mdx b/docs/community/developers/index.mdx similarity index 92% rename from docs/internals/developers/index.mdx rename to docs/community/developers/index.mdx index 7321329..a40876e 100644 --- a/docs/internals/developers/index.mdx +++ b/docs/community/developers/index.mdx @@ -19,11 +19,11 @@ This section covers everything you need to extend, adapt, or contribute to Zenzi ## In this section -- [Writing Plugin Rules](plugins.mdx) — implement `BaseRule` subclasses, register +- [Writing Plugin Rules](how-to/write-plugin.mdx) — implement `BaseRule` subclasses, register them via `entry_points`, and satisfy the pickle / purity contract. -- [Writing an Adapter](writing-an-adapter.mdx) — implement the `BaseAdapter` protocol +- [Writing an Adapter](how-to/implement-adapter.mdx) — implement the `BaseAdapter` protocol to teach Zenzic about a new documentation engine. -- [Example Projects](examples.mdx) — four self-contained runnable fixtures that +- [Example Projects](tutorials/adapter-examples.mdx) — four self-contained runnable fixtures that demonstrate correct and incorrect Zenzic configurations. --- diff --git a/docs/community/developers/reference/_category_.json b/docs/community/developers/reference/_category_.json new file mode 100644 index 0000000..48c7bc4 --- /dev/null +++ b/docs/community/developers/reference/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Reference", + "key": "dev-reference" +} diff --git a/docs/internals/reference/api.mdx b/docs/community/developers/reference/adapter-api.mdx similarity index 100% rename from docs/internals/reference/api.mdx rename to docs/community/developers/reference/adapter-api.mdx diff --git a/docs/internals/sentinel-style-guide.mdx b/docs/community/developers/reference/sentinel-style.mdx similarity index 98% rename from docs/internals/sentinel-style-guide.mdx rename to docs/community/developers/reference/sentinel-style.mdx index 09def01..eafc99b 100644 --- a/docs/internals/sentinel-style-guide.mdx +++ b/docs/community/developers/reference/sentinel-style.mdx @@ -40,7 +40,7 @@ Every card in a `
` block must have exactly: Everything you need to install, configure, and integrate Zenzic into your CI/CD workflow. - [ Explore the Guide](../usage/index.mdx) + [ Explore the Guide](../../../how-to/install.mdx) ``` ### Forbidden patterns diff --git a/docs/community/developers/tutorials/_category_.json b/docs/community/developers/tutorials/_category_.json new file mode 100644 index 0000000..97ee5d6 --- /dev/null +++ b/docs/community/developers/tutorials/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Tutorials", + "key": "dev-tutorials" +} diff --git a/docs/internals/developers/examples.mdx b/docs/community/developers/tutorials/adapter-examples.mdx similarity index 100% rename from docs/internals/developers/examples.mdx rename to docs/community/developers/tutorials/adapter-examples.mdx diff --git a/docs/community/faqs.mdx b/docs/community/faqs.mdx index b83ecac..e5741fd 100644 --- a/docs/community/faqs.mdx +++ b/docs/community/faqs.mdx @@ -61,7 +61,7 @@ assets, or external URLs. Yes. Zenzic works on any folder of Markdown files without requiring a build engine at all (Vanilla mode). Native adapters for MkDocs, Zensical, and other engines add nav-awareness and i18n support. -Third-party adapters can extend this to any other engine. See the [Engines guide](../guides/engines.mdx) +Third-party adapters can extend this to any other engine. See the [Engines guide](../reference/engines.mdx) for details. --- @@ -109,7 +109,7 @@ and same-page anchors (if `validate_same_page_anchors: true` is set). run: uvx zenzic check all --strict ``` -For the full setup with dynamic badges and regression detection, see the [CI/CD guide](../guides/ci-cd.mdx). +For the full setup with dynamic badges and regression detection, see the [CI/CD guide](../how-to/configure-ci-cd.mdx). **What does the `--strict` flag do?** diff --git a/docs/community/index.mdx b/docs/community/index.mdx index 9013898..1d0e13b 100644 --- a/docs/community/index.mdx +++ b/docs/community/index.mdx @@ -26,7 +26,7 @@ ecosystem tools referenced in this documentation are third-party projects. The design philosophy and long-term direction behind Zenzic. - [ Read](../philosophy.mdx) + [ Read](../explanation/safe-harbor.mdx) -   __License__ diff --git a/docs/ecosystem/_category_.json b/docs/ecosystem/_category_.json deleted file mode 100644 index 13b6b31..0000000 --- a/docs/ecosystem/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Ecosystem", - "position": 4, - "link": { - "type": "generated-index", - "description": "Adapters, integrations, and how Zenzic fits into your documentation pipeline." - } -} diff --git a/docs/examples/_category_.json b/docs/examples/_category_.json deleted file mode 100644 index f551b6e..0000000 --- a/docs/examples/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Examples", - "position": 7, - "link": { - "type": "generated-index", - "description": "Reference projects that demonstrate Zenzic in real-world scenarios." - } -} diff --git a/docs/explanation/_category_.json b/docs/explanation/_category_.json new file mode 100644 index 0000000..a24a724 --- /dev/null +++ b/docs/explanation/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "Explanation", + "position": 5, + "link": { + "type": "generated-index" + } +} diff --git a/docs/internals/architecture-overview.mdx b/docs/explanation/architecture.mdx similarity index 99% rename from docs/internals/architecture-overview.mdx rename to docs/explanation/architecture.mdx index c1619ff..975b0c1 100644 --- a/docs/internals/architecture-overview.mdx +++ b/docs/explanation/architecture.mdx @@ -6,7 +6,7 @@ description: Technical deep dive into Zenzic's Two-Pass Pipeline, Shield middlew # Architecture -This page describes the internal design of Zenzic for contributors and advanced users who need to understand how the tool works under the hood. For configuration and usage, see the [Configuration Reference](../guides/configuration-reference) and [Checks Reference](../guides/checks). +This page describes the internal design of Zenzic for contributors and advanced users who need to understand how the tool works under the hood. For configuration and usage, see the [Configuration Reference](../reference/configuration-reference) and [Checks Reference](../reference/checks). --- @@ -462,7 +462,7 @@ In parallel mode: ## Integrations Layer {#integrations-layer} -The `zenzic.integrations` namespace contains **opt-in plugins** that hook into an external build engine's lifecycle and invoke Zenzic checks as a quality gate. Integrations are the **Arm** of the [Mind and Arm model](../ecosystem/overview) — they act, whereas Adapters interpret. +The `zenzic.integrations` namespace contains **opt-in plugins** that hook into an external build engine's lifecycle and invoke Zenzic checks as a quality gate. Integrations are the **Arm** of the [Mind and Arm model](./ecosystem) — they act, whereas Adapters interpret. ### Design Contract {#integrations-contract} diff --git a/docs/guides/discovery.mdx b/docs/explanation/discovery.mdx similarity index 100% rename from docs/guides/discovery.mdx rename to docs/explanation/discovery.mdx diff --git a/docs/ecosystem/overview.mdx b/docs/explanation/ecosystem.mdx similarity index 93% rename from docs/ecosystem/overview.mdx rename to docs/explanation/ecosystem.mdx index ba8225f..c015f9f 100644 --- a/docs/ecosystem/overview.mdx +++ b/docs/explanation/ecosystem.mdx @@ -129,6 +129,6 @@ zenzic = "zenzic.integrations.mkdocs:ZenzicPlugin" ## See Also {#see-also} -- [Architecture Reference](../internals/architecture-overview) — Deep dive into the Adapter Protocol and `BaseAdapter` contract. -- [Discovery & Exclusion](../guides/discovery) — How Zenzic discovers files before the Adapter is consulted. -- [Configuration Reference](../guides/configuration-reference) — `[build_context]` engine selection and `zenzic.toml` options. +- [Architecture Reference](./architecture) — Deep dive into the Adapter Protocol and `BaseAdapter` contract. +- [Discovery & Exclusion](./discovery) — How Zenzic discovers files before the Adapter is consulted. +- [Configuration Reference](../reference/configuration-reference) — `[build_context]` engine selection and `zenzic.toml` options. diff --git a/docs/philosophy.mdx b/docs/explanation/safe-harbor.mdx similarity index 100% rename from docs/philosophy.mdx rename to docs/explanation/safe-harbor.mdx diff --git a/docs/guides/_category_.json b/docs/guides/_category_.json deleted file mode 100644 index 6ba3046..0000000 --- a/docs/guides/_category_.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "label": "Reference", - "position": 3, - "key": "reference-guides", - "link": { - "type": "generated-index", - "description": "Configuration reference, engine adapters, CI/CD integration, and migration." - } -} diff --git a/docs/how-to/_category_.json b/docs/how-to/_category_.json new file mode 100644 index 0000000..c499383 --- /dev/null +++ b/docs/how-to/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "How-to Guides", + "position": 3, + "link": { + "type": "generated-index" + } +} diff --git a/docs/usage/badges.mdx b/docs/how-to/add-badges.mdx similarity index 96% rename from docs/usage/badges.mdx rename to docs/how-to/add-badges.mdx index 1962d35..248726b 100644 --- a/docs/usage/badges.mdx +++ b/docs/how-to/add-badges.mdx @@ -40,7 +40,7 @@ Use this badge for strict pipelines where any broken link, dead anchor, or leake run: uvx zenzic check all --strict ``` -Place the `passing` URL in your README. If this step fails in CI, manually swap the badge to `failing` — or automate it via [dynamic-badges-action](https://github.com/Schneegans/dynamic-badges-action) (see [CI/CD Integration](../guides/ci-cd.mdx)). +Place the `passing` URL in your README. If this step fails in CI, manually swap the badge to `failing` — or automate it via [dynamic-badges-action](https://github.com/Schneegans/dynamic-badges-action) (see [CI/CD Integration](./configure-ci-cd.mdx)). --- @@ -108,7 +108,7 @@ Then reference the dynamic endpoint in your README: [![Zenzic Score](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com///raw/zenzic-score.json)](https://github.com/PythonWoods/zenzic) ``` -**Setup:** create a Gist, generate a Personal Access Token with `gist` scope, save it as `GIST_SECRET` in your repo secrets, and replace ``. See [CI/CD Integration](../guides/ci-cd.mdx) for the complete workflow. +**Setup:** create a Gist, generate a Personal Access Token with `gist` scope, save it as `GIST_SECRET` in your repo secrets, and replace ``. See [CI/CD Integration](./configure-ci-cd.mdx) for the complete workflow. --- diff --git a/docs/guides/custom-rules-dsl.mdx b/docs/how-to/add-custom-rules.mdx similarity index 98% rename from docs/guides/custom-rules-dsl.mdx rename to docs/how-to/add-custom-rules.mdx index 9d3aa97..de86890 100644 --- a/docs/guides/custom-rules-dsl.mdx +++ b/docs/how-to/add-custom-rules.mdx @@ -83,7 +83,7 @@ Rules with `severity = "info"` are printed without the `│` snippet. the project uses `MkDocsAdapter`, `ZensicalAdapter`, or `VanillaAdapter`. The rule engine operates on raw Markdown text; it has no knowledge of the build engine. This means: -- Rules you write for a MkDocs project require no changes after [migrating to Zensical](../guides/migration.mdx). +- Rules you write for a MkDocs project require no changes after [migrating to Zensical](./migrate-engines.mdx). - Rules are safe to write before deciding which build engine a project will use. --- diff --git a/docs/usage/advanced.mdx b/docs/how-to/advanced-options.mdx similarity index 99% rename from docs/usage/advanced.mdx rename to docs/how-to/advanced-options.mdx index 0d21f50..fdedc60 100644 --- a/docs/usage/advanced.mdx +++ b/docs/how-to/advanced-options.mdx @@ -269,7 +269,7 @@ immediately — before any file is scanned. local to each worker process and discarded on completion — results will differ from sequential mode silently. Return all state as `RuleFinding` objects. -See [Writing Plugin Rules](../internals/developers/plugins.mdx) for the complete contract, +See [Writing Plugin Rules](../community/developers/how-to/write-plugin.mdx) for the complete contract, examples, and packaging instructions. --- diff --git a/docs/guides/adapters-config.mdx b/docs/how-to/configure-adapter.mdx similarity index 98% rename from docs/guides/adapters-config.mdx rename to docs/how-to/configure-adapter.mdx index f41e8f9..4d4e83c 100644 --- a/docs/guides/adapters-config.mdx +++ b/docs/how-to/configure-adapter.mdx @@ -203,4 +203,4 @@ Python packages — no Zenzic update required. Adapters register themselves unde hugo = "zenzic_hugo.adapter:HugoAdapter" ``` -See [Writing an Adapter](../internals/developers/writing-an-adapter.mdx) for the full protocol. +See [Writing an Adapter](../community/developers/how-to/implement-adapter.mdx) for the full protocol. diff --git a/docs/guides/ci-cd.mdx b/docs/how-to/configure-ci-cd.mdx similarity index 99% rename from docs/guides/ci-cd.mdx rename to docs/how-to/configure-ci-cd.mdx index b0431c4..1a85e11 100644 --- a/docs/guides/ci-cd.mdx +++ b/docs/how-to/configure-ci-cd.mdx @@ -243,4 +243,4 @@ Combine with branch protection rules to block merges that degrade documentation | **`2`** | **Zenzic Shield: credential detected** | **Rotate credential immediately** | | **`3`** | **Blood Sentinel: path traversal detected** | **Remove offending link immediately** | -> For the full badge copy-paste reference, see [Official Badges](../usage/badges.mdx). +> For the full badge copy-paste reference, see [Official Badges](./add-badges.mdx). diff --git a/docs/usage/index.mdx b/docs/how-to/install.mdx similarity index 95% rename from docs/usage/index.mdx rename to docs/how-to/install.mdx index 66d4651..2274521 100644 --- a/docs/usage/index.mdx +++ b/docs/how-to/install.mdx @@ -200,7 +200,7 @@ placeholder_max_words = 30 # technical reference pages are intentionally bri fail_under = 70 # establish an initial quality floor ``` -See the [Configuration Reference](../guides/index.mdx) for the full field list. +See the [Configuration Reference](../reference/index.mdx) for the full field list. ### 3. Check — run continuously {#check} @@ -237,7 +237,7 @@ root, Zenzic loads the corresponding **adapter** which provides: as orphans. - **Ghost Routes** — when `mkdocs-material` with `reconfigure_material: true` generates locale entry points (e.g. `/it/`) at build time, those pages never appear in `nav:`. Zenzic - marks them `REACHABLE` automatically in the [Virtual Site Map](../guides/checks#vsm-how-it-works) + marks them `REACHABLE` automatically in the [Virtual Site Map](../reference/checks#vsm-how-it-works) so they are never reported as false orphans — with no manual exclusion list required. ### Vanilla mode {#vanilla-mode} @@ -263,6 +263,6 @@ zenzic check all --engine mkdocs # force MkDocs adapter **Next steps:** -- [CLI Commands reference](commands.mdx) — every command, flag, and exit code -- [Advanced features](advanced.mdx) — Reference integrity, Shield, programmatic usage -- [CI/CD Integration](../guides/ci-cd.mdx) — GitHub Actions, pre-commit hooks, baseline management +- [CLI Commands reference](../reference/cli.mdx) — every command, flag, and exit code +- [Advanced features](./advanced-options.mdx) — Reference integrity, Shield, programmatic usage +- [CI/CD Integration](./configure-ci-cd.mdx) — GitHub Actions, pre-commit hooks, baseline management diff --git a/docs/guides/migration.mdx b/docs/how-to/migrate-engines.mdx similarity index 99% rename from docs/guides/migration.mdx rename to docs/how-to/migrate-engines.mdx index b7ecc95..bffe0ad 100644 --- a/docs/guides/migration.mdx +++ b/docs/how-to/migrate-engines.mdx @@ -191,7 +191,7 @@ reported as orphans. :::info[CLI bridge — Global flags] Engine migration changes adapters, not Sentinel policy. Keep run behavior aligned with -[CLI Commands: Global flags](../usage/commands.mdx#global-flags): +[CLI Commands: Global flags](../reference/cli.mdx#global-flags): 1. `--strict` for hard-gate validation during cutover. 2. `--exit-zero` for observation windows without breaking the pipeline. diff --git a/docs/index.mdx b/docs/index.mdx index 79dbc74..9f25d8a 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 1 +sidebar_position: 0 sidebar_label: "Overview" --- @@ -17,11 +17,11 @@ credentials, and enforce quality rules — without ever running the documentatio | Goal | Page | | :--- | :--- | -| Install Zenzic and run your first check | [Introduction](./intro) | -| Understand which checks Zenzic runs | [Checks Reference](./guides/checks) | -| Configure `zenzic.toml` | [Configuration Reference](./guides/configuration-reference) | -| Integrate with GitHub Actions | [CI/CD Integration](./guides/ci-cd) | -| Explore the internal architecture | [Architecture Overview](./internals/architecture-overview) | +| Install Zenzic and run your first check | [First Audit](./tutorials/first-audit) | +| Understand which checks Zenzic runs | [Checks Reference](./reference/checks) | +| Configure `zenzic.toml` | [Configuration Reference](./reference/configuration-reference) | +| Integrate with GitHub Actions | [CI/CD Integration](./how-to/configure-ci-cd) | +| Explore the internal architecture | [Architecture Overview](./explanation/architecture) | | Contribute to the project | [Contributing](./community/contribute/index.mdx) | ## Quick start diff --git a/docs/internals/_category_.json b/docs/internals/_category_.json deleted file mode 100644 index 8ddd159..0000000 --- a/docs/internals/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Engineering", - "position": 5, - "link": { - "type": "generated-index", - "description": "Architecture, ADRs, security model, and developer references." - } -} diff --git a/docs/internals/adr/_category_.json b/docs/internals/adr/_category_.json deleted file mode 100644 index 0ee8215..0000000 --- a/docs/internals/adr/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Architecture Decision Records", - "position": 7, - "link": { - "type": "generated-index", - "description": "Recorded architectural decisions and their rationale." - } -} diff --git a/docs/internals/developers/_category_.json b/docs/internals/developers/_category_.json deleted file mode 100644 index c36c974..0000000 --- a/docs/internals/developers/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Developers", - "position": 8, - "link": { - "type": "generated-index", - "description": "Plugin SDK, adapter authoring, and contributor tooling." - } -} diff --git a/docs/internals/reference/_category_.json b/docs/internals/reference/_category_.json deleted file mode 100644 index 414c586..0000000 --- a/docs/internals/reference/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Reference", - "position": 9, - "link": { - "type": "generated-index", - "description": "Internal API surface and data model reference." - } -} diff --git a/docs/internals/security/_category_.json b/docs/internals/security/_category_.json deleted file mode 100644 index 35ee255..0000000 --- a/docs/internals/security/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Security", - "position": 10, - "link": { - "type": "generated-index", - "description": "Threat model, Shield internals, and Blood Sentinel." - } -} diff --git a/docs/reference/_category_.json b/docs/reference/_category_.json new file mode 100644 index 0000000..9b5c74a --- /dev/null +++ b/docs/reference/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Reference", + "position": 4 +} diff --git a/docs/guides/checks.mdx b/docs/reference/checks.mdx similarity index 100% rename from docs/guides/checks.mdx rename to docs/reference/checks.mdx diff --git a/docs/usage/commands.mdx b/docs/reference/cli.mdx similarity index 98% rename from docs/usage/commands.mdx rename to docs/reference/cli.mdx index 5364873..7a4e9ea 100644 --- a/docs/usage/commands.mdx +++ b/docs/reference/cli.mdx @@ -176,7 +176,7 @@ Exit code 3 is issued when the Blood Sentinel detects a link that resolves to an system directory (`/etc/`, `/root/`, `/var/`, `/proc/`, `/sys/`, `/usr/`). Unlike exit code 1, this is a security incident and takes priority over all other exit codes. It is never suppressed by `--exit-zero`. See -[Checks: Blood Sentinel](../guides/checks#blood-sentinel) for details. +[Checks: Blood Sentinel](./checks#blood-sentinel) for details. ::: --- @@ -269,7 +269,7 @@ Install a third-party adapter or choose from the list above. ``` Third-party adapters are discovered automatically once installed — no Zenzic update required. -See [Writing an Adapter](../internals/developers/writing-an-adapter.mdx). +See [Writing an Adapter](../community/developers/how-to/implement-adapter.mdx). --- diff --git a/docs/guides/configuration-reference.mdx b/docs/reference/configuration-reference.mdx similarity index 100% rename from docs/guides/configuration-reference.mdx rename to docs/reference/configuration-reference.mdx diff --git a/docs/guides/core-settings.mdx b/docs/reference/configuration.mdx similarity index 100% rename from docs/guides/core-settings.mdx rename to docs/reference/configuration.mdx diff --git a/docs/guides/engines.mdx b/docs/reference/engines.mdx similarity index 99% rename from docs/guides/engines.mdx rename to docs/reference/engines.mdx index fe25169..a0a96ab 100644 --- a/docs/guides/engines.mdx +++ b/docs/reference/engines.mdx @@ -64,7 +64,7 @@ If `[build_context]` is absent entirely, Zenzic deterministically discovers the :::info[CLI bridge — Signal-to-noise controls] Engine selection and Sentinel verbosity are independent concerns. Use -[CLI Commands: Global flags](../usage/commands.mdx#global-flags) to tune policy per run: +[CLI Commands: Global flags](./cli.mdx#global-flags) to tune policy per run: 1. `--strict` to elevate warnings and enforce external URL validation. 2. `--exit-zero` for non-blocking observation runs. diff --git a/docs/internals/findings-codes.mdx b/docs/reference/finding-codes.mdx similarity index 100% rename from docs/internals/findings-codes.mdx rename to docs/reference/finding-codes.mdx diff --git a/docs/guides/glossary.mdx b/docs/reference/glossary.mdx similarity index 97% rename from docs/guides/glossary.mdx rename to docs/reference/glossary.mdx index 457b3d8..2c28ecc 100644 --- a/docs/guides/glossary.mdx +++ b/docs/reference/glossary.mdx @@ -14,7 +14,7 @@ This glossary provides precise definitions for all domain-specific terms used in A build-engine-specific module that implements the `BaseAdapter` protocol. Adapters translate between a documentation engine's file conventions (nav structure, locale directories, URL mapping) and Zenzic's engine-agnostic core. Built-in adapters: `MkDocsAdapter`, `ZensicalAdapter`, `DocusaurusAdapter`, `VanillaAdapter`. Third-party adapters can be registered via the `zenzic.adapters` entry-point group. -See: [Architecture -- Adapter Protocol](../internals/architecture-overview#adapter-protocol) +See: [Architecture -- Adapter Protocol](../explanation/architecture#adapter-protocol) --- @@ -59,7 +59,7 @@ The 4-level hierarchy that determines which files and directories Zenzic scans. The hierarchy is evaluated top-to-bottom; the first matching rule wins. System Guardrails (L1) can never be overridden. -See: [Discovery & Exclusion](./discovery) +See: [Discovery & Exclusion](../explanation/discovery) --- @@ -128,7 +128,7 @@ Zenzic's core analysis architecture. The pipeline processes each Markdown file i Pass 2 only begins when Pass 1 completes without Shield findings. This is the Shield-as-firewall guarantee: no further analysis is performed on files that contain leaked credentials. -See: [Architecture -- Two-Pass Pipeline](../internals/architecture-overview#two-pass-pipeline) +See: [Architecture -- Two-Pass Pipeline](../explanation/architecture#two-pass-pipeline) --- diff --git a/docs/guides/index.mdx b/docs/reference/index.mdx similarity index 93% rename from docs/guides/index.mdx rename to docs/reference/index.mdx index e50088b..9e3b24a 100644 --- a/docs/guides/index.mdx +++ b/docs/reference/index.mdx @@ -68,9 +68,9 @@ This reference is split into focused pages: | Page | Contents | | :--- | :--- | -| [Core Settings](core-settings.mdx) | `docs_dir`, exclusion lists, thresholds, scoring, loading behaviour | -| [Adapters & Engine](adapters-config.mdx) | `build_context`, adapter auto-detection, `--engine` override | -| [Custom Rules DSL](custom-rules-dsl.mdx) | `[[custom_rules]]` — project-specific regex lint rules in pure TOML | +| [Core Settings](./configuration.mdx) | `docs_dir`, exclusion lists, thresholds, scoring, loading behaviour | +| [Adapters & Engine](./configuration-reference.mdx) | `build_context`, adapter auto-detection, `--engine` override | +| [Custom Rules DSL](../how-to/add-custom-rules.mdx) | `[[custom_rules]]` — project-specific regex lint rules in pure TOML | --- diff --git a/docs/tutorials/_category_.json b/docs/tutorials/_category_.json new file mode 100644 index 0000000..9db740a --- /dev/null +++ b/docs/tutorials/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "Tutorials", + "position": 2, + "link": { + "type": "generated-index" + } +} diff --git a/docs/examples/overview.mdx b/docs/tutorials/examples.mdx similarity index 96% rename from docs/examples/overview.mdx rename to docs/tutorials/examples.mdx index c2c9721..42ef174 100644 --- a/docs/examples/overview.mdx +++ b/docs/tutorials/examples.mdx @@ -206,6 +206,6 @@ Intentionally triggers the Zenzic Shield (credential detection) and the link che ## See Also {#see-also} -- [Ecosystem Overview](../ecosystem/overview) — Adapter vs Integration model. -- [Discovery & Exclusion](../guides/discovery) — How the Layered Exclusion hierarchy works. -- [Checks Reference](../guides/checks) — All available `zenzic check` commands and their findings. +- [Ecosystem Overview](../explanation/ecosystem) — Adapter vs Integration model. +- [Discovery & Exclusion](../explanation/discovery) — How the Layered Exclusion hierarchy works. +- [Checks Reference](../reference/checks) — All available `zenzic check` commands and their findings. diff --git a/docs/intro.mdx b/docs/tutorials/first-audit.mdx similarity index 97% rename from docs/intro.mdx rename to docs/tutorials/first-audit.mdx index 6bc4f97..9b3f789 100644 --- a/docs/intro.mdx +++ b/docs/tutorials/first-audit.mdx @@ -52,7 +52,7 @@ To use the `ZenzicPlugin` inside `mkdocs build`, install the optional `[mkdocs]` pip install "zenzic[mkdocs]" ``` -This adds `mkdocs>=1.6.1` as a dependency and enables the `zenzic.integrations.mkdocs` entry point. See the [Ecosystem overview](./ecosystem/overview) for the full Adapter vs. Integration model. +This adds `mkdocs>=1.6.1` as a dependency and enables the `zenzic.integrations.mkdocs` entry point. See the [Ecosystem overview](../explanation/ecosystem) for the full Adapter vs. Integration model. --- diff --git a/docs/usage/_category_.json b/docs/usage/_category_.json deleted file mode 100644 index 334ff8e..0000000 --- a/docs/usage/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Usage", - "position": 2, - "link": { - "type": "generated-index", - "description": "Install, configure, and run Zenzic on your documentation." - } -} diff --git a/i18n/it/docusaurus-plugin-content-docs/current/community/brand-kit.mdx b/i18n/it/docusaurus-plugin-content-docs/current/community/brand-kit.mdx index d197f6b..fb784d4 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/community/brand-kit.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/community/brand-kit.mdx @@ -52,7 +52,7 @@ che non possono raggiungere `img.shields.io`: | Shield | ![Zenzic Shield](../assets/brand/svg/zenzic-badge-shield.svg) | Gate binario: passing / failing | | Score | ![Zenzic Score](../assets/brand/svg/zenzic-badge-score.svg) | Metrica di qualità: 0–100 | -Per i varianti dinamici Shields.io e il wiring CI/CD, vedi la [guida ai Badge](../usage/badges.mdx). +Per i varianti dinamici Shields.io e il wiring CI/CD, vedi la [guida ai Badge](../how-to/add-badges.mdx). ## Download diff --git a/i18n/it/docusaurus-plugin-content-docs/current/community/developers/_category_.json b/i18n/it/docusaurus-plugin-content-docs/current/community/developers/_category_.json new file mode 100644 index 0000000..f3887f8 --- /dev/null +++ b/i18n/it/docusaurus-plugin-content-docs/current/community/developers/_category_.json @@ -0,0 +1,3 @@ +{ + "label": "Guida per Sviluppatori" +} diff --git a/i18n/it/docusaurus-plugin-content-docs/current/community/developers/explanation/_category_.json b/i18n/it/docusaurus-plugin-content-docs/current/community/developers/explanation/_category_.json new file mode 100644 index 0000000..4a86f5d --- /dev/null +++ b/i18n/it/docusaurus-plugin-content-docs/current/community/developers/explanation/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Spiegazione", + "key": "dev-explanation" +} diff --git a/i18n/it/docusaurus-plugin-content-docs/current/internals/adr/003-discovery-logic.mdx b/i18n/it/docusaurus-plugin-content-docs/current/community/developers/explanation/adr-discovery.mdx similarity index 100% rename from i18n/it/docusaurus-plugin-content-docs/current/internals/adr/003-discovery-logic.mdx rename to i18n/it/docusaurus-plugin-content-docs/current/community/developers/explanation/adr-discovery.mdx diff --git a/i18n/it/docusaurus-plugin-content-docs/current/internals/arch_gaps.mdx b/i18n/it/docusaurus-plugin-content-docs/current/community/developers/explanation/architecture-gaps.mdx similarity index 100% rename from i18n/it/docusaurus-plugin-content-docs/current/internals/arch_gaps.mdx rename to i18n/it/docusaurus-plugin-content-docs/current/community/developers/explanation/architecture-gaps.mdx diff --git a/i18n/it/docusaurus-plugin-content-docs/current/community/developers/how-to/_category_.json b/i18n/it/docusaurus-plugin-content-docs/current/community/developers/how-to/_category_.json new file mode 100644 index 0000000..3123995 --- /dev/null +++ b/i18n/it/docusaurus-plugin-content-docs/current/community/developers/how-to/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Guide Pratiche", + "key": "dev-how-to" +} diff --git a/i18n/it/docusaurus-plugin-content-docs/current/internals/developers/writing-an-adapter.mdx b/i18n/it/docusaurus-plugin-content-docs/current/community/developers/how-to/implement-adapter.mdx similarity index 98% rename from i18n/it/docusaurus-plugin-content-docs/current/internals/developers/writing-an-adapter.mdx rename to i18n/it/docusaurus-plugin-content-docs/current/community/developers/how-to/implement-adapter.mdx index c310aa5..c0af890 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/internals/developers/writing-an-adapter.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/community/developers/how-to/implement-adapter.mdx @@ -329,11 +329,11 @@ def test_nav_paths_relative() -> None: Collega il codice dell'adapter alla verità operativa del progetto: 1. Registra l'identità engine nella configurazione del progetto tramite `[build_context] engine` - (vedi [Adapter e Configurazione del Motore](../../guides/adapters-config.mdx)). + (vedi [Adapter e Configurazione del Motore](../../../how-to/configure-adapter.mdx)). 2. Valida il comportamento dell'adapter in policy Sentinel strict: `zenzic check all --engine myengine --strict`. - Per i controlli di esecuzione, vedi [Comandi CLI: Flag globali](../../usage/commands.mdx#global-flags). + Per i controlli di esecuzione, vedi [Comandi CLI: Flag globali](../../../reference/cli.mdx#global-flags). 3. Se il tuo engine genera route locali sintetiche, mappa esplicitamente le aspettative Ghost Route rispetto al riferimento VSM: - [Riferimento Controlli — VSM](../../guides/checks#vsm-how-it-works). + [Riferimento Controlli — VSM](../../../reference/checks#vsm-how-it-works). ::: diff --git a/i18n/it/docusaurus-plugin-content-docs/current/internals/developers/plugins.mdx b/i18n/it/docusaurus-plugin-content-docs/current/community/developers/how-to/write-plugin.mdx similarity index 98% rename from i18n/it/docusaurus-plugin-content-docs/current/internals/developers/plugins.mdx rename to i18n/it/docusaurus-plugin-content-docs/current/community/developers/how-to/write-plugin.mdx index 2353b3c..a2edced 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/internals/developers/plugins.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/community/developers/how-to/write-plugin.mdx @@ -303,10 +303,10 @@ Zenzic. (vedi [Abilitare i plugin](#enabling-plugins)). 2. Valida la regola in semantica pipeline strict: `zenzic check all --strict`. - Per i controlli di run, vedi [Comandi CLI: Flag globali](../../usage/commands.mdx#global-flags). + Per i controlli di run, vedi [Comandi CLI: Flag globali](../../../reference/cli.mdx#global-flags). 3. Se la regola è nav-aware, mappa il comportamento atteso delle Ghost Route rispetto al modello VSM: - [Riferimento Controlli — VSM](../../guides/checks#vsm-how-it-works). + [Riferimento Controlli — VSM](../../../reference/checks#vsm-how-it-works). ::: -[api-baserule]: ../reference/api.mdx +[api-baserule]: ../reference/adapter-api.mdx diff --git a/i18n/it/docusaurus-plugin-content-docs/current/internals/developers/index.mdx b/i18n/it/docusaurus-plugin-content-docs/current/community/developers/index.mdx similarity index 92% rename from i18n/it/docusaurus-plugin-content-docs/current/internals/developers/index.mdx rename to i18n/it/docusaurus-plugin-content-docs/current/community/developers/index.mdx index d4ff760..06e90cd 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/internals/developers/index.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/community/developers/index.mdx @@ -21,11 +21,11 @@ Zenzic. ## In questa sezione -- [Scrivere Regole Plugin](plugins.mdx) — implementa sottoclassi `BaseRule`, +- [Scrivere Regole Plugin](how-to/write-plugin.mdx) — implementa sottoclassi `BaseRule`, registrale tramite `entry_points` e soddisfa il contratto pickle / purezza. -- [Scrivere un Adapter](writing-an-adapter.mdx) — implementa il protocollo +- [Scrivere un Adapter](how-to/implement-adapter.mdx) — implementa il protocollo `BaseAdapter` per insegnare a Zenzic a gestire un nuovo motore di documentazione. -- [Progetti di Esempio](examples.mdx) — quattro fixture eseguibili auto-contenuti che +- [Progetti di Esempio](tutorials/adapter-examples.mdx) — quattro fixture eseguibili auto-contenuti che dimostrano configurazioni Zenzic corrette e non. --- diff --git a/i18n/it/docusaurus-plugin-content-docs/current/community/developers/reference/_category_.json b/i18n/it/docusaurus-plugin-content-docs/current/community/developers/reference/_category_.json new file mode 100644 index 0000000..50ff706 --- /dev/null +++ b/i18n/it/docusaurus-plugin-content-docs/current/community/developers/reference/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Riferimento", + "key": "dev-reference" +} diff --git a/i18n/it/docusaurus-plugin-content-docs/current/internals/reference/api.mdx b/i18n/it/docusaurus-plugin-content-docs/current/community/developers/reference/adapter-api.mdx similarity index 100% rename from i18n/it/docusaurus-plugin-content-docs/current/internals/reference/api.mdx rename to i18n/it/docusaurus-plugin-content-docs/current/community/developers/reference/adapter-api.mdx diff --git a/i18n/it/docusaurus-plugin-content-docs/current/internals/sentinel-style-guide.mdx b/i18n/it/docusaurus-plugin-content-docs/current/community/developers/reference/sentinel-style.mdx similarity index 98% rename from i18n/it/docusaurus-plugin-content-docs/current/internals/sentinel-style-guide.mdx rename to i18n/it/docusaurus-plugin-content-docs/current/community/developers/reference/sentinel-style.mdx index 7554711..d0cd700 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/internals/sentinel-style-guide.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/community/developers/reference/sentinel-style.mdx @@ -40,7 +40,7 @@ Ogni card in un blocco `
` deve avere esattament Tutto ciò che serve per installare, configurare e integrare Zenzic nel tuo workflow CI/CD. - [ Esplora la Guida](../usage/index.mdx) + [ Esplora la Guida](../../../how-to/install.mdx) ``` ### Pattern vietati diff --git a/i18n/it/docusaurus-plugin-content-docs/current/community/developers/tutorials/_category_.json b/i18n/it/docusaurus-plugin-content-docs/current/community/developers/tutorials/_category_.json new file mode 100644 index 0000000..f150e18 --- /dev/null +++ b/i18n/it/docusaurus-plugin-content-docs/current/community/developers/tutorials/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Tutorial", + "key": "dev-tutorials" +} diff --git a/i18n/it/docusaurus-plugin-content-docs/current/internals/developers/examples.mdx b/i18n/it/docusaurus-plugin-content-docs/current/community/developers/tutorials/adapter-examples.mdx similarity index 100% rename from i18n/it/docusaurus-plugin-content-docs/current/internals/developers/examples.mdx rename to i18n/it/docusaurus-plugin-content-docs/current/community/developers/tutorials/adapter-examples.mdx diff --git a/i18n/it/docusaurus-plugin-content-docs/current/community/faqs.mdx b/i18n/it/docusaurus-plugin-content-docs/current/community/faqs.mdx index 1649ecf..effd4a8 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/community/faqs.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/community/faqs.mdx @@ -60,7 +60,7 @@ per personalizzare il comportamento, ad esempio per escludere directory, asset o Sì. Zenzic funziona su qualsiasi cartella di file Markdown senza richiedere alcun motore di build (modalità Vanilla). Gli adapter nativi per MkDocs e Zensical aggiungono la consapevolezza della nav e il supporto i18n. Adapter di terze parti possono estendere questa funzionalità a -qualsiasi altro motore. Consulta la guida [Motori](../guides/engines.mdx) per i dettagli. +qualsiasi altro motore. Consulta la guida [Motori](../reference/engines.mdx) per i dettagli. ## Checks e risultati @@ -106,7 +106,7 @@ link di definizione e anchor interni (se `validate_same_page_anchors: true`). ``` Per la configurazione completa con badge dinamici e rilevamento regressioni, consulta la -guida [CI/CD](../guides/ci-cd.mdx). +guida [CI/CD](../how-to/configure-ci-cd.mdx). **Cosa fa il flag `--strict`?** diff --git a/i18n/it/docusaurus-plugin-content-docs/current/community/index.mdx b/i18n/it/docusaurus-plugin-content-docs/current/community/index.mdx index 6921bb0..2424cb2 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/community/index.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/community/index.mdx @@ -26,7 +26,7 @@ strumenti dell'ecosistema citati in questa documentazione sono progetti di terze La filosofia di design e la direzione a lungo termine di Zenzic. - [ Leggi](../philosophy.mdx) + [ Leggi](../explanation/safe-harbor.mdx) -   __Licenza__ diff --git a/i18n/it/docusaurus-plugin-content-docs/current/ecosystem/_category_.json b/i18n/it/docusaurus-plugin-content-docs/current/ecosystem/_category_.json deleted file mode 100644 index db08d01..0000000 --- a/i18n/it/docusaurus-plugin-content-docs/current/ecosystem/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Ecosistema", - "position": 4, - "link": { - "type": "generated-index", - "description": "Adapter, integrazioni e il modello Mente/Braccio di Zenzic." - } -} diff --git a/i18n/it/docusaurus-plugin-content-docs/current/examples/_category_.json b/i18n/it/docusaurus-plugin-content-docs/current/examples/_category_.json deleted file mode 100644 index 71ae587..0000000 --- a/i18n/it/docusaurus-plugin-content-docs/current/examples/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Esempi", - "position": 7, - "link": { - "type": "generated-index", - "description": "Progetti di riferimento che dimostrano Zenzic in scenari reali." - } -} diff --git a/i18n/it/docusaurus-plugin-content-docs/current/explanation/_category_.json b/i18n/it/docusaurus-plugin-content-docs/current/explanation/_category_.json new file mode 100644 index 0000000..9878950 --- /dev/null +++ b/i18n/it/docusaurus-plugin-content-docs/current/explanation/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "Spiegazione", + "position": 5, + "link": { + "type": "generated-index" + } +} diff --git a/i18n/it/docusaurus-plugin-content-docs/current/internals/architecture-overview.mdx b/i18n/it/docusaurus-plugin-content-docs/current/explanation/architecture.mdx similarity index 99% rename from i18n/it/docusaurus-plugin-content-docs/current/internals/architecture-overview.mdx rename to i18n/it/docusaurus-plugin-content-docs/current/explanation/architecture.mdx index 5379179..41f6b02 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/internals/architecture-overview.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/explanation/architecture.mdx @@ -277,7 +277,7 @@ def _validate_docs_root(repo_root: Path, docs_root: Path) -> None: ## LayeredExclusionManager — Interni {#exclusion-internals} -Il `LayeredExclusionManager` e il cuore del sistema di esclusione a 4 livelli. I suoi interni sono documentati in dettaglio nella pagina [Discovery e Esclusione](../guides/discovery). +Il `LayeredExclusionManager` e il cuore del sistema di esclusione a 4 livelli. I suoi interni sono documentati in dettaglio nella pagina [Discovery e Esclusione](./discovery). I punti salienti dal punto di vista architetturale: @@ -337,7 +337,7 @@ La soglia di 50 file (`ADAPTIVE_PARALLEL_THRESHOLD`) e un'euristica conservativa ## Layer delle Integrazioni {#integrations-layer} -Il namespace `zenzic.integrations` contiene **plugin opt-in** che si agganciano al ciclo di vita di un motore di build esterno e invocano i controlli di Zenzic come quality gate. Le integrazioni sono il **Braccio** del [modello Mente e Braccio](../ecosystem/overview) — agiscono, mentre gli Adapter interpretano. +Il namespace `zenzic.integrations` contiene **plugin opt-in** che si agganciano al ciclo di vita di un motore di build esterno e invocano i controlli di Zenzic come quality gate. Le integrazioni sono il **Braccio** del [modello Mente e Braccio](./ecosystem) — agiscono, mentre gli Adapter interpretano. ### Contratto di Progettazione {#integrations-contract} diff --git a/i18n/it/docusaurus-plugin-content-docs/current/guides/discovery.mdx b/i18n/it/docusaurus-plugin-content-docs/current/explanation/discovery.mdx similarity index 100% rename from i18n/it/docusaurus-plugin-content-docs/current/guides/discovery.mdx rename to i18n/it/docusaurus-plugin-content-docs/current/explanation/discovery.mdx diff --git a/i18n/it/docusaurus-plugin-content-docs/current/ecosystem/overview.mdx b/i18n/it/docusaurus-plugin-content-docs/current/explanation/ecosystem.mdx similarity index 93% rename from i18n/it/docusaurus-plugin-content-docs/current/ecosystem/overview.mdx rename to i18n/it/docusaurus-plugin-content-docs/current/explanation/ecosystem.mdx index c970544..3433541 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/ecosystem/overview.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/explanation/ecosystem.mdx @@ -130,6 +130,6 @@ zenzic = "zenzic.integrations.mkdocs:ZenzicPlugin" ## Vedi Anche {#see-also} -- [Riferimento Architettura](../internals/architecture-overview) — Approfondimento sul Protocollo Adapter e il contratto `BaseAdapter`. -- [Discovery e Esclusione](../guides/discovery) — Come Zenzic scopre i file prima che l'Adapter venga consultato. -- [Riferimento Configurazione](../guides/configuration-reference) — Selezione engine in `[build_context]` e opzioni `zenzic.toml`. +- [Riferimento Architettura](./architecture) — Approfondimento sul Protocollo Adapter e il contratto `BaseAdapter`. +- [Discovery e Esclusione](./discovery) — Come Zenzic scopre i file prima che l'Adapter venga consultato. +- [Riferimento Configurazione](../reference/configuration-reference) — Selezione engine in `[build_context]` e opzioni `zenzic.toml`. diff --git a/i18n/it/docusaurus-plugin-content-docs/current/philosophy.mdx b/i18n/it/docusaurus-plugin-content-docs/current/explanation/safe-harbor.mdx similarity index 100% rename from i18n/it/docusaurus-plugin-content-docs/current/philosophy.mdx rename to i18n/it/docusaurus-plugin-content-docs/current/explanation/safe-harbor.mdx diff --git a/i18n/it/docusaurus-plugin-content-docs/current/guides/_category_.json b/i18n/it/docusaurus-plugin-content-docs/current/guides/_category_.json deleted file mode 100644 index 05307ad..0000000 --- a/i18n/it/docusaurus-plugin-content-docs/current/guides/_category_.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "label": "Riferimento", - "position": 3, - "key": "reference-guides", - "link": { - "type": "generated-index", - "description": "Riferimento configurazione, adapter, CI/CD e migrazione." - } -} diff --git a/i18n/it/docusaurus-plugin-content-docs/current/how-to/_category_.json b/i18n/it/docusaurus-plugin-content-docs/current/how-to/_category_.json new file mode 100644 index 0000000..4be52fc --- /dev/null +++ b/i18n/it/docusaurus-plugin-content-docs/current/how-to/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "Guide Pratiche", + "position": 3, + "link": { + "type": "generated-index" + } +} diff --git a/i18n/it/docusaurus-plugin-content-docs/current/usage/badges.mdx b/i18n/it/docusaurus-plugin-content-docs/current/how-to/add-badges.mdx similarity index 98% rename from i18n/it/docusaurus-plugin-content-docs/current/usage/badges.mdx rename to i18n/it/docusaurus-plugin-content-docs/current/how-to/add-badges.mdx index fb25562..8961e13 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/usage/badges.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/how-to/add-badges.mdx @@ -40,7 +40,7 @@ Usa questo badge per le pipeline strict in cui qualsiasi link non funzionante, a run: uvx zenzic check all --strict ``` -Inserisci l'URL `passing` nel tuo README. Se questo step fallisce in CI, sostituisci manualmente il badge con `failing` — oppure automatizzalo tramite [dynamic-badges-action](https://github.com/Schneegans/dynamic-badges-action) (vedi [Integrazione CI/CD](../guides/ci-cd.mdx)). +Inserisci l'URL `passing` nel tuo README. Se questo step fallisce in CI, sostituisci manualmente il badge con `failing` — oppure automatizzalo tramite [dynamic-badges-action](https://github.com/Schneegans/dynamic-badges-action) (vedi [Integrazione CI/CD](./configure-ci-cd.mdx)). --- @@ -108,7 +108,7 @@ Poi inserisci l'endpoint dinamico nel tuo README: [![Zenzic Score](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com///raw/zenzic-score.json)](https://github.com/PythonWoods/zenzic) ``` -**Configurazione:** crea un Gist, genera un Personal Access Token con scope `gist`, salvalo come `GIST_SECRET` nei segreti del repository e sostituisci ``. Vedi [Integrazione CI/CD](../guides/ci-cd.mdx) per il workflow completo. +**Configurazione:** crea un Gist, genera un Personal Access Token con scope `gist`, salvalo come `GIST_SECRET` nei segreti del repository e sostituisci ``. Vedi [Integrazione CI/CD](./configure-ci-cd.mdx) per il workflow completo. --- diff --git a/i18n/it/docusaurus-plugin-content-docs/current/guides/custom-rules-dsl.mdx b/i18n/it/docusaurus-plugin-content-docs/current/how-to/add-custom-rules.mdx similarity index 98% rename from i18n/it/docusaurus-plugin-content-docs/current/guides/custom-rules-dsl.mdx rename to i18n/it/docusaurus-plugin-content-docs/current/how-to/add-custom-rules.mdx index 2c6526b..01ebe8e 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/guides/custom-rules-dsl.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/how-to/add-custom-rules.mdx @@ -78,7 +78,7 @@ Le regole con `severity = "info"` vengono stampate senza lo snippet `│`. **Le regole custom sono indipendenti dall'adapter.** Una regola che cerca `DRAFT` si attiva identicamente che il progetto usi `MkDocsAdapter`, `ZensicalAdapter` o `VanillaAdapter`. Questo significa che le regole scritte per un progetto MkDocs non richiedono modifiche dopo la -[migrazione a Zensical](../guides/migration.mdx). +[migrazione a Zensical](./migrate-engines.mdx). --- diff --git a/i18n/it/docusaurus-plugin-content-docs/current/usage/advanced.mdx b/i18n/it/docusaurus-plugin-content-docs/current/how-to/advanced-options.mdx similarity index 99% rename from i18n/it/docusaurus-plugin-content-docs/current/usage/advanced.mdx rename to i18n/it/docusaurus-plugin-content-docs/current/how-to/advanced-options.mdx index 3e8d7ec..7f2b1c5 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/usage/advanced.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/how-to/advanced-options.mdx @@ -266,7 +266,7 @@ costruzione del motore (**validazione anticipata**). Una regola non serializzabile solleva `PluginContractError` immediatamente — prima che venga scansionato qualsiasi file. -Vedi [Scrivere Regole Plugin](../internals/developers/plugins.mdx) per il contratto +Vedi [Scrivere Regole Plugin](../community/developers/how-to/write-plugin.mdx) per il contratto completo, esempi e istruzioni di pacchettizzazione. --- diff --git a/i18n/it/docusaurus-plugin-content-docs/current/guides/adapters-config.mdx b/i18n/it/docusaurus-plugin-content-docs/current/how-to/configure-adapter.mdx similarity index 98% rename from i18n/it/docusaurus-plugin-content-docs/current/guides/adapters-config.mdx rename to i18n/it/docusaurus-plugin-content-docs/current/how-to/configure-adapter.mdx index d19da6b..3a4bdfc 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/guides/adapters-config.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/how-to/configure-adapter.mdx @@ -195,4 +195,4 @@ registrano sotto il gruppo di entry-point `zenzic.adapters` nel loro `pyproject. hugo = "zenzic_hugo.adapter:HugoAdapter" ``` -Consulta [Scrivere un Adapter](../internals/developers/writing-an-adapter.mdx) per il protocollo completo. +Consulta [Scrivere un Adapter](../community/developers/how-to/implement-adapter.mdx) per il protocollo completo. diff --git a/i18n/it/docusaurus-plugin-content-docs/current/guides/ci-cd.mdx b/i18n/it/docusaurus-plugin-content-docs/current/how-to/configure-ci-cd.mdx similarity index 99% rename from i18n/it/docusaurus-plugin-content-docs/current/guides/ci-cd.mdx rename to i18n/it/docusaurus-plugin-content-docs/current/how-to/configure-ci-cd.mdx index 8ceb8aa..8b73ba2 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/guides/ci-cd.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/how-to/configure-ci-cd.mdx @@ -237,4 +237,4 @@ Combina con le branch protection rules per bloccare i merge che degradano la qua | **`2`** | **Zenzic Shield: credenziale rilevata** | **Ruota la credenziale immediatamente** | | **`3`** | **Blood Sentinel: path traversal rilevato** | **Rimuovi il link incriminato immediatamente** | -> Per il riferimento completo dei badge pronti all'uso, vedi [Badge Ufficiali](../usage/badges.mdx). +> Per il riferimento completo dei badge pronti all'uso, vedi [Badge Ufficiali](./add-badges.mdx). diff --git a/i18n/it/docusaurus-plugin-content-docs/current/usage/index.mdx b/i18n/it/docusaurus-plugin-content-docs/current/how-to/install.mdx similarity index 95% rename from i18n/it/docusaurus-plugin-content-docs/current/usage/index.mdx rename to i18n/it/docusaurus-plugin-content-docs/current/how-to/install.mdx index f7510ae..3cc6497 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/usage/index.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/how-to/install.mdx @@ -196,7 +196,7 @@ placeholder_max_words = 30 # le pagine di reference tecnico sono intenzional fail_under = 70 # stabilisce un quality floor iniziale ``` -Consulta la [Guida alla Configurazione](../guides/index.mdx) per l'elenco completo dei campi. +Consulta la [Guida alla Configurazione](../reference/index.mdx) per l'elenco completo dei campi. ### 3. Check — esegui in modo continuativo {#check} @@ -259,6 +259,6 @@ zenzic check all --engine mkdocs # forza l'adapter MkDocs **Prossimi passi:** -- [Riferimento comandi CLI](commands.mdx) — ogni comando, flag e codice di uscita -- [Funzionalità avanzate](advanced.mdx) — integrità dei riferimenti, Shield, utilizzo programmatico -- [Integrazione CI/CD](../guides/ci-cd.mdx) — GitHub Actions, pre-commit hook, gestione del baseline +- [Riferimento comandi CLI](../reference/cli.mdx) — ogni comando, flag e codice di uscita +- [Funzionalità avanzate](./advanced-options.mdx) — integrità dei riferimenti, Shield, utilizzo programmatico +- [Integrazione CI/CD](./configure-ci-cd.mdx) — GitHub Actions, pre-commit hook, gestione del baseline diff --git a/i18n/it/docusaurus-plugin-content-docs/current/guides/migration.mdx b/i18n/it/docusaurus-plugin-content-docs/current/how-to/migrate-engines.mdx similarity index 99% rename from i18n/it/docusaurus-plugin-content-docs/current/guides/migration.mdx rename to i18n/it/docusaurus-plugin-content-docs/current/how-to/migrate-engines.mdx index 145ac71..fc276ff 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/guides/migration.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/how-to/migrate-engines.mdx @@ -193,7 +193,7 @@ Map in modo che non vengano mai segnalate come orfane. :::info[Ponte CLI — Flag globali] La migrazione engine cambia gli adapter, non la policy Sentinel. Mantieni il comportamento -di esecuzione allineato a [Comandi CLI: Flag globali](../usage/commands.mdx#global-flags): +di esecuzione allineato a [Comandi CLI: Flag globali](../reference/cli.mdx#global-flags): 1. `--strict` per validazione hard-gate durante il cutover. 2. `--exit-zero` per finestre di osservazione senza interrompere la pipeline. diff --git a/i18n/it/docusaurus-plugin-content-docs/current/index.mdx b/i18n/it/docusaurus-plugin-content-docs/current/index.mdx index d38f2ab..0ecc4d6 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/index.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/index.mdx @@ -17,11 +17,11 @@ e applicare regole di qualità — senza mai eseguire il build della documentazi | Obiettivo | Pagina | | :--- | :--- | -| Installare Zenzic ed eseguire il primo controllo | [Introduzione](./intro) | -| Capire quali controlli esegue Zenzic | [Riferimento Controlli](./guides/checks) | -| Configurare `zenzic.toml` | [Riferimento Configurazione](./guides/configuration-reference) | -| Integrare con GitHub Actions | [Integrazione CI/CD](./guides/ci-cd) | -| Esplorare l'architettura interna | [Panoramica Architettura](./internals/architecture-overview) | +| Installare Zenzic ed eseguire il primo controllo | [Primo Audit](./tutorials/first-audit) | +| Capire quali controlli esegue Zenzic | [Riferimento Controlli](./reference/checks) | +| Configurare `zenzic.toml` | [Riferimento Configurazione](./reference/configuration-reference) | +| Integrare con GitHub Actions | [Integrazione CI/CD](./how-to/configure-ci-cd) | +| Esplorare l'architettura interna | [Panoramica Architettura](./explanation/architecture) | | Contribuire al progetto | [Guida ai Contributi](./community/contribute/index.mdx) | ## Avvio rapido diff --git a/i18n/it/docusaurus-plugin-content-docs/current/internals/_category_.json b/i18n/it/docusaurus-plugin-content-docs/current/internals/_category_.json deleted file mode 100644 index 2a1cbab..0000000 --- a/i18n/it/docusaurus-plugin-content-docs/current/internals/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Ingegneria", - "position": 5, - "link": { - "type": "generated-index", - "description": "Architettura, ADR, modello di sicurezza e riferimenti per sviluppatori." - } -} diff --git a/i18n/it/docusaurus-plugin-content-docs/current/internals/adr/_category_.json b/i18n/it/docusaurus-plugin-content-docs/current/internals/adr/_category_.json deleted file mode 100644 index d75f9dc..0000000 --- a/i18n/it/docusaurus-plugin-content-docs/current/internals/adr/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Decisioni Architetturali", - "position": 7, - "link": { - "type": "generated-index", - "description": "Decisioni architetturali registrate e le loro motivazioni." - } -} diff --git a/i18n/it/docusaurus-plugin-content-docs/current/internals/developers/_category_.json b/i18n/it/docusaurus-plugin-content-docs/current/internals/developers/_category_.json deleted file mode 100644 index c29526d..0000000 --- a/i18n/it/docusaurus-plugin-content-docs/current/internals/developers/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Sviluppatori", - "position": 8, - "link": { - "type": "generated-index", - "description": "Plugin SDK, creazione adapter e strumenti per contributori." - } -} diff --git a/i18n/it/docusaurus-plugin-content-docs/current/internals/reference/_category_.json b/i18n/it/docusaurus-plugin-content-docs/current/internals/reference/_category_.json deleted file mode 100644 index 68e11b4..0000000 --- a/i18n/it/docusaurus-plugin-content-docs/current/internals/reference/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Riferimento", - "position": 9, - "link": { - "type": "generated-index", - "description": "Superficie API interna e riferimento del modello dati." - } -} diff --git a/i18n/it/docusaurus-plugin-content-docs/current/internals/security/_category_.json b/i18n/it/docusaurus-plugin-content-docs/current/internals/security/_category_.json deleted file mode 100644 index 45e2a49..0000000 --- a/i18n/it/docusaurus-plugin-content-docs/current/internals/security/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Sicurezza", - "position": 10, - "link": { - "type": "generated-index", - "description": "Modello di minaccia, Shield e Blood Sentinel." - } -} diff --git a/i18n/it/docusaurus-plugin-content-docs/current/reference/_category_.json b/i18n/it/docusaurus-plugin-content-docs/current/reference/_category_.json new file mode 100644 index 0000000..b3df0aa --- /dev/null +++ b/i18n/it/docusaurus-plugin-content-docs/current/reference/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Riferimento", + "position": 4 +} diff --git a/i18n/it/docusaurus-plugin-content-docs/current/guides/checks.mdx b/i18n/it/docusaurus-plugin-content-docs/current/reference/checks.mdx similarity index 100% rename from i18n/it/docusaurus-plugin-content-docs/current/guides/checks.mdx rename to i18n/it/docusaurus-plugin-content-docs/current/reference/checks.mdx diff --git a/i18n/it/docusaurus-plugin-content-docs/current/usage/commands.mdx b/i18n/it/docusaurus-plugin-content-docs/current/reference/cli.mdx similarity index 98% rename from i18n/it/docusaurus-plugin-content-docs/current/usage/commands.mdx rename to i18n/it/docusaurus-plugin-content-docs/current/reference/cli.mdx index 3e430e2..1cb42b9 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/usage/commands.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/reference/cli.mdx @@ -180,7 +180,7 @@ Il codice 3 viene emesso quando il Blood Sentinel rileva un link che risolve ver directory di sistema dell'OS (`/etc/`, `/root/`, `/var/`, `/proc/`, `/sys/`, `/usr/`). A differenza del codice 1, questo è un incidente di sicurezza e ha priorità su tutti gli altri codici di uscita. Non viene mai soppresso da `--exit-zero`. Consultare -[Controlli: Blood Sentinel](../guides/checks#blood-sentinel) per i dettagli. +[Controlli: Blood Sentinel](./checks#blood-sentinel) per i dettagli. ::: --- @@ -271,7 +271,7 @@ Install a third-party adapter or choose from the list above. ``` Gli adapter di terze parti vengono scoperti automaticamente una volta installati — nessun -aggiornamento Zenzic richiesto. Vedi [Scrivere un Adapter](../internals/developers/writing-an-adapter.mdx). +aggiornamento Zenzic richiesto. Vedi [Scrivere un Adapter](../community/developers/how-to/implement-adapter.mdx). --- diff --git a/i18n/it/docusaurus-plugin-content-docs/current/guides/configuration-reference.mdx b/i18n/it/docusaurus-plugin-content-docs/current/reference/configuration-reference.mdx similarity index 100% rename from i18n/it/docusaurus-plugin-content-docs/current/guides/configuration-reference.mdx rename to i18n/it/docusaurus-plugin-content-docs/current/reference/configuration-reference.mdx diff --git a/i18n/it/docusaurus-plugin-content-docs/current/guides/core-settings.mdx b/i18n/it/docusaurus-plugin-content-docs/current/reference/configuration.mdx similarity index 100% rename from i18n/it/docusaurus-plugin-content-docs/current/guides/core-settings.mdx rename to i18n/it/docusaurus-plugin-content-docs/current/reference/configuration.mdx diff --git a/i18n/it/docusaurus-plugin-content-docs/current/guides/engines.mdx b/i18n/it/docusaurus-plugin-content-docs/current/reference/engines.mdx similarity index 99% rename from i18n/it/docusaurus-plugin-content-docs/current/guides/engines.mdx rename to i18n/it/docusaurus-plugin-content-docs/current/reference/engines.mdx index 51ac6aa..5eaf169 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/guides/engines.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/reference/engines.mdx @@ -68,7 +68,7 @@ Se `[build_context]` è assente, Zenzic individua deterministicamente il motore: :::info[Ponte CLI — Controlli signal-to-noise] Selezione engine e verbosità Sentinel sono aspetti separati. Usa -[Comandi CLI: Flag globali](../usage/commands.mdx#global-flags) per calibrare la policy per run: +[Comandi CLI: Flag globali](./cli.mdx#global-flags) per calibrare la policy per run: 1. `--strict` per elevare warning e imporre validazione URL esterni. 2. `--exit-zero` per run osservativi non bloccanti. diff --git a/i18n/it/docusaurus-plugin-content-docs/current/internals/findings-codes.mdx b/i18n/it/docusaurus-plugin-content-docs/current/reference/finding-codes.mdx similarity index 100% rename from i18n/it/docusaurus-plugin-content-docs/current/internals/findings-codes.mdx rename to i18n/it/docusaurus-plugin-content-docs/current/reference/finding-codes.mdx diff --git a/i18n/it/docusaurus-plugin-content-docs/current/guides/glossary.mdx b/i18n/it/docusaurus-plugin-content-docs/current/reference/glossary.mdx similarity index 96% rename from i18n/it/docusaurus-plugin-content-docs/current/guides/glossary.mdx rename to i18n/it/docusaurus-plugin-content-docs/current/reference/glossary.mdx index 80824b9..0f563df 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/guides/glossary.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/reference/glossary.mdx @@ -12,7 +12,7 @@ Questo glossario raccoglie la terminologia tecnica di Zenzic. I termini sono in ### Adapter {#adapter} -Componente che media tra il core di Zenzic e un motore di build specifico (MkDocs, Zensical, Docusaurus). Ogni adapter implementa il protocollo `BaseAdapter` e fornisce la risoluzione dei percorsi locale-aware, la mappa di navigazione e la classificazione delle route. Gli adapter vengono scoperti tramite il gruppo entry-point `zenzic.adapters` e istanziati dalla factory `get_adapter`. Vedi [Architettura -- Protocollo Adapter](../internals/architecture-overview#adapter-protocol). +Componente che media tra il core di Zenzic e un motore di build specifico (MkDocs, Zensical, Docusaurus). Ogni adapter implementa il protocollo `BaseAdapter` e fornisce la risoluzione dei percorsi locale-aware, la mappa di navigazione e la classificazione delle route. Gli adapter vengono scoperti tramite il gruppo entry-point `zenzic.adapters` e istanziati dalla factory `get_adapter`. Vedi [Architettura -- Protocollo Adapter](../explanation/architecture#adapter-protocol). --- @@ -33,7 +33,7 @@ Il sistema a quattro livelli che determina quali file e directory vengono inclus | L3 | Configurazione | `excluded_dirs`, `excluded_file_patterns` da `zenzic.toml` o `[tool.zenzic]` in `pyproject.toml` | | L4 | CLI | `--exclude-dir`, `--include-dir` per override temporanei | -Il `LayeredExclusionManager` orchestra tutti i livelli. Vedi [Discovery e Esclusione](./discovery#four-level-hierarchy). +Il `LayeredExclusionManager` orchestra tutti i livelli. Vedi [Discovery e Esclusione](../explanation/discovery#four-level-hierarchy). --- @@ -75,7 +75,7 @@ Un file `.md` che esiste fisicamente su disco ma non compare nella navigazione d ### Pipeline a Due Passate {#two-pass-pipeline} -L'architettura fondamentale di Zenzic. La prima passata raccoglie i riferimenti, scansiona lo Shield e costruisce la ReferenceMap. La seconda passata valida i link, risolve i percorsi e verifica le ancore. Questa separazione garantisce che la cross-check dei riferimenti avvenga solo dopo che tutte le definizioni sono state raccolte, e che lo Shield abbia la priorità assoluta. Vedi [Architettura -- Pipeline a Due Passate](../internals/architecture-overview#two-pass-pipeline). +L'architettura fondamentale di Zenzic. La prima passata raccoglie i riferimenti, scansiona lo Shield e costruisce la ReferenceMap. La seconda passata valida i link, risolve i percorsi e verifica le ancore. Questa separazione garantisce che la cross-check dei riferimenti avvenga solo dopo che tutte le definizioni sono state raccolte, e che lo Shield abbia la priorità assoluta. Vedi [Architettura -- Pipeline a Due Passate](../explanation/architecture#two-pass-pipeline). --- diff --git a/i18n/it/docusaurus-plugin-content-docs/current/guides/index.mdx b/i18n/it/docusaurus-plugin-content-docs/current/reference/index.mdx similarity index 93% rename from i18n/it/docusaurus-plugin-content-docs/current/guides/index.mdx rename to i18n/it/docusaurus-plugin-content-docs/current/reference/index.mdx index 93d8a6d..4996fc2 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/guides/index.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/reference/index.mdx @@ -64,9 +64,9 @@ comportamento: | Pagina | Contenuto | | :--- | :--- | -| [Impostazioni di Base](core-settings.mdx) | `docs_dir`, liste di esclusione, soglie, punteggio | -| [Adapter e Motore](adapters-config.mdx) | `build_context`, auto-rilevamento adapter, override `--engine` | -| [DSL Regole Custom](custom-rules-dsl.mdx) | `[[custom_rules]]` — regole lint personalizzate in puro TOML | +| [Impostazioni di Base](./configuration.mdx) | `docs_dir`, liste di esclusione, soglie, punteggio | +| [Adapter e Motore](./configuration-reference.mdx) | `build_context`, auto-rilevamento adapter, override `--engine` | +| [DSL Regole Custom](../how-to/add-custom-rules.mdx) | `[[custom_rules]]` — regole lint personalizzate in puro TOML | --- diff --git a/i18n/it/docusaurus-plugin-content-docs/current/tutorials/_category_.json b/i18n/it/docusaurus-plugin-content-docs/current/tutorials/_category_.json new file mode 100644 index 0000000..85a6387 --- /dev/null +++ b/i18n/it/docusaurus-plugin-content-docs/current/tutorials/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "Tutorial", + "position": 2, + "link": { + "type": "generated-index" + } +} diff --git a/i18n/it/docusaurus-plugin-content-docs/current/examples/overview.mdx b/i18n/it/docusaurus-plugin-content-docs/current/tutorials/examples.mdx similarity index 96% rename from i18n/it/docusaurus-plugin-content-docs/current/examples/overview.mdx rename to i18n/it/docusaurus-plugin-content-docs/current/tutorials/examples.mdx index 15e5e26..bdfd595 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/examples/overview.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/tutorials/examples.mdx @@ -207,6 +207,6 @@ Attiva intenzionalmente lo Zenzic Shield (rilevamento credenziali) e il link che ## Vedi Anche {#see-also} -- [Panoramica Ecosistema](../ecosystem/overview) — Modello Adapter vs Integrazione. -- [Discovery e Esclusione](../guides/discovery) — Come funziona la gerarchia di esclusione a livelli. -- [Riferimento Controlli](../guides/checks) — Tutti i comandi `zenzic check` disponibili e i loro risultati. +- [Panoramica Ecosistema](../explanation/ecosystem) — Modello Adapter vs Integrazione. +- [Discovery e Esclusione](../explanation/discovery) — Come funziona la gerarchia di esclusione a livelli. +- [Riferimento Controlli](../reference/checks) — Tutti i comandi `zenzic check` disponibili e i loro risultati. diff --git a/i18n/it/docusaurus-plugin-content-docs/current/intro.mdx b/i18n/it/docusaurus-plugin-content-docs/current/tutorials/first-audit.mdx similarity index 96% rename from i18n/it/docusaurus-plugin-content-docs/current/intro.mdx rename to i18n/it/docusaurus-plugin-content-docs/current/tutorials/first-audit.mdx index 296e0a5..86dccf1 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/intro.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/tutorials/first-audit.mdx @@ -52,7 +52,7 @@ Per usare `ZenzicPlugin` all'interno di `mkdocs build`, installa l'extra opziona pip install "zenzic[mkdocs]" ``` -Questo aggiunge `mkdocs>=1.6.1` come dipendenza e abilita l'entry point `zenzic.integrations.mkdocs`. Consulta la [panoramica dell'ecosistema](./ecosystem/overview) per il modello completo Adapter vs. Integrazione. +Questo aggiunge `mkdocs>=1.6.1` come dipendenza e abilita l'entry point `zenzic.integrations.mkdocs`. Consulta la [panoramica dell'ecosistema](../explanation/ecosystem) per il modello completo Adapter vs. Integrazione. --- diff --git a/i18n/it/docusaurus-plugin-content-docs/current/usage/_category_.json b/i18n/it/docusaurus-plugin-content-docs/current/usage/_category_.json deleted file mode 100644 index d7f80e9..0000000 --- a/i18n/it/docusaurus-plugin-content-docs/current/usage/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Utilizzo", - "position": 2, - "link": { - "type": "generated-index", - "description": "Installa, configura ed esegui Zenzic sulla tua documentazione." - } -} diff --git a/sidebars.ts b/sidebars.ts index de4d078..f3607bd 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -2,83 +2,9 @@ import type {SidebarsConfig} from '@docusaurus/plugin-content-docs'; const sidebars: SidebarsConfig = { tutorialSidebar: [ - 'intro', - 'philosophy', { - type: 'category', - label: 'User Guide', - link: {type: 'generated-index', description: 'Install, configure, and run Zenzic on your documentation.'}, - items: [ - 'usage/index', - 'usage/commands', - 'usage/advanced', - 'usage/badges', - ], - }, - { - type: 'category', - label: 'Developers', - link: {type: 'generated-index', description: 'Extend Zenzic with custom adapters, plugin rules, and integrations.'}, - items: [ - 'internals/developers/index', - 'internals/developers/writing-an-adapter', - 'internals/developers/plugins', - 'internals/developers/examples', - ], - }, - { - type: 'category', - label: 'Reference', - link: {type: 'generated-index', description: 'Configuration reference, engine adapters, and custom rules.'}, - items: [ - 'guides/checks', - 'guides/configuration-reference', - 'guides/discovery', - 'guides/custom-rules-dsl', - 'guides/engines', - 'guides/adapters-config', - 'guides/core-settings', - 'guides/ci-cd', - 'guides/migration', - 'guides/glossary', - ], - }, - { - type: 'category', - label: 'Ecosystem', - link: {type: 'generated-index', description: 'Adapters, integrations, and how Zenzic fits into your documentation pipeline.'}, - items: [ - 'ecosystem/overview', - ], - }, - { - type: 'category', - label: 'Community', - link: {type: 'generated-index', description: 'Contribute, report bugs, request features, and explore the project.'}, - items: [ - { - type: 'category', - label: 'How to Contribute', - link: {type: 'doc', id: 'community/contribute/index'}, - items: [ - 'community/contribute/pull-requests', - 'community/contribute/report-a-bug', - 'community/contribute/report-a-docs-issue', - 'community/contribute/request-a-change', - ], - }, - 'community/faqs', - 'community/brand-kit', - 'community/license', - ], - }, - { - type: 'category', - label: 'Examples', - link: {type: 'generated-index', description: 'Reference projects that demonstrate Zenzic in real-world scenarios.'}, - items: [ - 'examples/overview', - ], + type: 'autogenerated', + dirName: '.', }, ], }; diff --git a/src/components/Homepage/Hero.tsx b/src/components/Homepage/Hero.tsx index fcb5c80..787e92f 100644 --- a/src/components/Homepage/Hero.tsx +++ b/src/components/Homepage/Hero.tsx @@ -13,7 +13,7 @@ export function SentinelBadge(): React.JSX.Element { } export default function Hero(): React.JSX.Element { - const docsHref = useBaseUrl('/docs/intro'); + const docsHref = useBaseUrl('/docs/'); const iconUrl = useBaseUrl('/assets/brand/svg/zenzic-icon.svg'); return ( diff --git a/zenzic.toml b/zenzic.toml index 3704a1b..c926f2d 100644 --- a/zenzic.toml +++ b/zenzic.toml @@ -1,21 +1,28 @@ # SPDX-FileCopyrightText: 2026 PythonWoods # SPDX-License-Identifier: Apache-2.0 -docs_dir = "docs" +# --- CORE SETTINGS --- +docs_dir = "docs" +fail_under = 100 +strict = true +# --- EXTERNAL VALIDATION --- excluded_external_urls = [ "https://docs.github.com/en/authentication/managing-commit-signature-verification/", ] # --- PROTEZIONE DOGFOODING --- -# The documentation explains placeholder patterns by example, so the checker -# would produce false positives on every page that describes its own rules. +# Placeholder checks disabled: the documentation explains placeholder patterns +# by example, so the checker would produce false positives on pages that +# describe its own rules. placeholder_patterns = [] placeholder_max_words = 0 -# --- ESCLUSIONE ASSET --- -# _category_.json are Docusaurus sidebar metadata consumed by the build tool, -# not referenced by any Markdown page. +# --- GESTIONE ASSET & STRUTTURA --- +# _category_.json files are Docusaurus sidebar metadata consumed by the build +# tool, not referenced by any Markdown page. They are excluded from the +# "Unused Assets" check; the DocusaurusAdapter still reads them to validate +# directory index integrity. excluded_assets = [ "**/_category_.json", "static/brand/**", @@ -23,10 +30,7 @@ excluded_assets = [ "static/img/favicon.ico", ] -# --- REGOLE DI QUALITÀ --- -fail_under = 100 -strict = true - +# --- ENGINE CONTEXT (Obsidian Glass Stable) --- [build_context] engine = "docusaurus" base_url = "/" From 8080a46ec872540b035dc5da81c4445bebc6ab6c Mon Sep 17 00:00:00 2001 From: PythonWoods Date: Mon, 20 Apr 2026 21:46:14 +0200 Subject: [PATCH 10/13] fix(i18n): align IT index.mdx sidebar_position to 0 (mirrors EN) --- i18n/it/docusaurus-plugin-content-docs/current/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/it/docusaurus-plugin-content-docs/current/index.mdx b/i18n/it/docusaurus-plugin-content-docs/current/index.mdx index 0ecc4d6..ed5cc7a 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/index.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/index.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 1 +sidebar_position: 0 sidebar_label: "Panoramica" --- From 923bab2bf0ff60db64f485fb9838e70b26c0b9ce Mon Sep 17 00:00:00 2001 From: PythonWoods Date: Mon, 20 Apr 2026 22:36:57 +0200 Subject: [PATCH 11/13] chore: add start:en and start:it scripts; start defaults to EN locale --- package.json | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/package.json b/package.json index b0add7f..d238231 100644 --- a/package.json +++ b/package.json @@ -4,7 +4,9 @@ "private": true, "scripts": { "docusaurus": "docusaurus", - "start": "docusaurus start", + "start": "docusaurus start --locale en", + "start:en": "docusaurus start --locale en", + "start:it": "docusaurus start --locale it", "build": "docusaurus build", "swizzle": "docusaurus swizzle", "deploy": "docusaurus deploy", From 03431ac7c444b2430c577dba02488761ad14e334 Mon Sep 17 00:00:00 2001 From: PythonWoods Date: Mon, 20 Apr 2026 22:39:01 +0200 Subject: [PATCH 12/13] fix(justfile): serve now calls npm run serve (build preview, EN+IT); add start-it --- justfile | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/justfile b/justfile index 3ae1bb3..1f4a9af 100644 --- a/justfile +++ b/justfile @@ -8,19 +8,19 @@ setup: npm ci -# Start local development server +# Start local development server (EN only — language switcher non funziona in dev) start: npm run start -# Alias for start -serve: - npm run start +# Start local development server in Italian +start-it: + npm run start:it -# Build production static site -build: - npm run build +# Serve production build locally (EN + IT, language switcher funzionante) +serve: + npm run serve -# Serve production build locally +# Alias for serve (preview production build) preview: npm run serve From 921bcb8f86108bbade2ffc9ca7209b6c34516a41 Mon Sep 17 00:00:00 2001 From: PythonWoods Date: Mon, 20 Apr 2026 22:43:41 +0200 Subject: [PATCH 13/13] fix(justfile): restore missing build recipe removed by previous edit --- justfile | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/justfile b/justfile index 1f4a9af..bea3b1b 100644 --- a/justfile +++ b/justfile @@ -24,6 +24,10 @@ serve: preview: npm run serve +# Build production static site +build: + npm run build + # Static type check typecheck: npm run typecheck