diff --git a/.bumpversion.toml b/.bumpversion.toml index 193cde6..df7171e 100644 --- a/.bumpversion.toml +++ b/.bumpversion.toml @@ -2,7 +2,7 @@ # SPDX-License-Identifier: Apache-2.0 [tool.bumpversion] -current_version = "0.9.2" +current_version = "0.10.0" parse = "(?P\\d+)\\.(?P\\d+)\\.(?P\\d+)" serialize = ["{major}.{minor}.{patch}"] diff --git a/.gitignore b/.gitignore index 2ffd96a..92efb4b 100644 --- a/.gitignore +++ b/.gitignore @@ -14,6 +14,7 @@ *.tsbuildinfo .eslintcache _zenzic_core/ +.zenzic_cache/ __pycache__/ # Misc @@ -52,3 +53,4 @@ mutmut* # VS Code Copilot agent definitions (local-only) .github/agents/ +.zenzic_cache/ diff --git a/.zenzic.toml b/.zenzic.toml index 1270bd7..1a271f0 100644 --- a/.zenzic.toml +++ b/.zenzic.toml @@ -38,8 +38,11 @@ excluded_external_urls = [ "https://spdx.org/licenses/", # GitHub PAT settings endpoint can intermittently time out from CI runners. "https://github.com/settings/tokens", - # GitHub API rate-limits unauthenticated CI runners (HTTP 429 / 403); prefix covers all github.com links. - #"https://github.com", + # External URLs excluded from the broken-link check to prevent CI flakiness + # caused by GitHub API rate-limiting and network timeouts. + "https://github.com/PythonWoods/zenzic", + "https://github.com/PythonWoods/zenzic-action", + "https://github.com/PythonWoods/zenzic-doc", # Facebook debugger consistently times out (>10 s) from CI environments. "https://developers.facebook.com/tools/debug/", # contributor-covenant.org consistently times out (> 10 s) from CI environments. @@ -197,3 +200,10 @@ it = "i18n/it/docusaurus-plugin-content-docs-developers/current" # uses: pythonwoods/zenzic-action@v1 # - name: Verify Badge Freshness # run: uvx zenzic score --check-stamp + +# --- NETWORK I/O --- +[network] +# Cache external link resolution in .zenzic_cache/external_links.json +# to eliminate network latency in CI and local re-runs. +# Set to 0 to disable caching entirely (synchronous fallback). +cache_ttl_hours = 24 diff --git a/CHANGELOG.md b/CHANGELOG.md index 54b1746..0bd2dc5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,50 +15,16 @@ No changes yet. --- -## [0.9.2] - 2026-06-05 +## [0.10.0] - 2026-06-06 ### Added -- **Engine Guide — Supported Engine Versions table:** Added "Supported Engine Versions" section to `docs/reference/engines.mdx` (EN + IT) documenting the supported major-version line for each adapter: MkDocs `1.x`, Zensical `0.0.x`, Docusaurus `3.x`, Standalone (agnostic). Clarifies that version constraints apply to the config-file schema, not the installed engine binary. -- **Z109 EXTERNAL_LINK_BROKEN:** Documented Z109 external link finding code (EN + IT) representing broken external URLs. -- **Diátaxis Compliance Refactoring:** Restructured documentation portal for strict Diátaxis compliance (Batches 1-4), renaming example directories from `docs/how-to/examples/` to `docs/tutorials/examples/` to correctly separate tutorials from how-tos. -- **Resolved route collisions and sidebar ordering:** Restructured examples and sidebar configurations to resolve overlapping routes and optimize navigation. - ---- - -## [0.9.1] - 2026-06-02 - -### Added - -- Z-Code Gallery completion (EN + IT) aligned with the full release scope. -- New documentation pages and galleries for `Z107 CIRCULAR_ANCHOR` and `Z104 FILE_NOT_FOUND`. - -### Changed - -- **Repository-Relative Suppression Config:** Updated `.zenzic.toml` `per_file_ignores` and `directory_policies` to use strictly repository-relative keys (prefixed with `docs/` or `docs/it/`). -- **Strategic Navigation Exemption:** Added `directory_policies` exemption for `docs/how-to/examples/**` under `Z401` to prevent scoring penalties on example directories that intentionally lack index files. -- **Score Badge telemetry:** Stamped quality score badge inline in `README.md` and `README.it.md` to show a passing score of `96/100`. -- Hostile Precision UI standardization applied across release-facing documentation surfaces. -- Terminal documentation debt removed by normalizing legacy snippets and inconsistent command narratives. -- SVG asset governance aligned with ADR-037 compliance requirements. - ---- - -## [0.9.0] - 2026-05-31 - -### Added - -- Historical archive split for v0.8.x and v0.7.x release notes under `changelogs/`. -- `tutorials/examples.mdx` (EN + IT): full gallery of all 20 `zenzic lab` sandboxes with scenario matrix, exit-code column, and per-scenario prose. -- 15 new gallery sections covering z102, z103, z105, z108, z202, z204, z301, z302, z303, z402, z403, z501, z502, z503, z505. -- `finding-codes.mdx` (EN + IT): Z204 CLI output updated to `POLICY VIOLATION DETECTED` banner. -- `privacy-gate.mdx` (EN + IT): Exit Behavior section and `[core]` table-header fix. +- **Native CI Integration and Filtering Docs:** Documented the new `--ci` shorthand and `--format github-annotations` in CLI Reference and CI/CD integration guides (EN + IT). Documented the `--only` flag for targeted rule filtering. +- **Blog Post:** Added new DevRel payload "Zenzic v0.10.0: Native GitHub Annotations and Progressive Adoption" demonstrating the killer features of v0.10.0. ### Changed -- Documentation for local gates now mirrors the real `just verify` recipe sequence (pre-commit hooks → pytest → strict audit → score stamp → freshness gate). -- Developers command matrix updated to remove obsolete preflight terminology. -- v0.8.x narratives archived; v0.9.0 sprint material moved to this entry. +- **ADR-037 Install Guide Refinement:** Removed the hardcoded version tag (`@v0.10.0`) from the Ephemeral GitHub execution instructions (`uvx --from git+...`) to decouple the command from temporal releases and point to the default branch. --- diff --git a/README.it.md b/README.it.md index 3cbbd47..8854746 100644 --- a/README.it.md +++ b/README.it.md @@ -23,7 +23,7 @@ SPDX-License-Identifier: Apache-2.0 [![REUSE 3.x compliant](https://img.shields.io/badge/REUSE-3.x%20compliant-0d9488?style=flat-square)](https://reuse.software/) [![License](https://img.shields.io/badge/license-Apache--2.0-0d9488?style=flat-square)](LICENSE) [![Documentation: Diátaxis](https://img.shields.io/badge/Docs-Di%C3%A1taxis-brightgreen?style=flat-square)](https://diataxis.fr/) -[![Zenzic](https://img.shields.io/badge/Zenzic-v0.9.2-blue?style=flat-square)](https://github.com/PythonWoods/zenzic) +[![Zenzic](https://img.shields.io/badge/Zenzic-v0.10.0-blue?style=flat-square)](https://github.com/PythonWoods/zenzic) --- diff --git a/README.md b/README.md index c52f1d3..0f46269 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ SPDX-License-Identifier: Apache-2.0 [![REUSE 3.x compliant](https://img.shields.io/badge/REUSE-3.x%20compliant-0d9488?style=flat-square)](https://reuse.software/) [![License](https://img.shields.io/badge/license-Apache--2.0-0d9488?style=flat-square)](LICENSE) [![Documentation: Diátaxis](https://img.shields.io/badge/Docs-Di%C3%A1taxis-brightgreen?style=flat-square)](https://diataxis.fr/) -[![Zenzic](https://img.shields.io/badge/Zenzic-v0.9.2-blue?style=flat-square)](https://github.com/PythonWoods/zenzic) +[![Zenzic](https://img.shields.io/badge/Zenzic-v0.10.0-blue?style=flat-square)](https://github.com/PythonWoods/zenzic) --- diff --git a/RELEASE.md b/RELEASE.md index 0b346ba..abfd2f0 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -8,9 +8,9 @@ | Field | Value | | :------- | :--------- | -| Version | v0.9.2 | +| Version | v0.10.0 | | Codename | Graphite | -| Date | 2026-06-05 | +| Date | 2026-06-06 | | Status | Stable | ## Release Checklist @@ -47,11 +47,11 @@ git checkout main git pull origin main # 3. Tag the main branch and push -git tag v0.9.2 +git tag v0.10.0 git push origin main --tags ``` -- [ ] Create GitHub Release from the tag, using the `## v0.9.2` CHANGELOG section as the release body. +- [ ] Create GitHub Release from the tag, using the `## v0.10.0` CHANGELOG section as the release body. ## Changelog Reference diff --git a/blog/2026-06-06-native-ci-integration-and-progressive-adoption.mdx b/blog/2026-06-06-native-ci-integration-and-progressive-adoption.mdx new file mode 100644 index 0000000..656ebcb --- /dev/null +++ b/blog/2026-06-06-native-ci-integration-and-progressive-adoption.mdx @@ -0,0 +1,50 @@ +--- +slug: zenzic-v0.10.0-native-github-annotations-and-progressive-adoption +title: "Zenzic v0.10.0: Async Engine, Native Annotations, and Progressive Adoption" +authors: [pythonwoods] +tags: [release, ci-cd, architecture] +--- + +{/* SPDX-FileCopyrightText: 2026 PythonWoods */} +{/* SPDX-License-Identifier: Apache-2.0 */} + +Zenzic v0.10.0 introduces a massive performance upgrade with a new **Async Network Engine**, alongside two architectural changes designed strictly for the CI/CD pipeline: **Native GitHub Annotations** and **Destructive Rule Filtering**. + +These features are not aesthetic. They are built to solve three specific operational bottlenecks: network-induced CI flakiness, context switching during Pull Request reviews, and the high friction of adopting static analysis in legacy documentation repositories. + +{/* truncate */} + +## Native GitHub Annotations (`--ci`) + +When a pipeline fails, developers do not want to dig through raw terminal logs to find the offending line of code. + +Zenzic v0.10.0 introduces the `--format github-annotations` formatter. Instead of drawing terminal UI panels, Zenzic emits raw `::error::` workflow commands. GitHub Actions parses these commands natively and injects them as inline annotations directly into the Pull Request diff. + +We also introduced the `--ci` shorthand flag. It performs two actions simultaneously: +1. Forces `--strict` mode (escalating all warnings to blocking errors). +2. Sets `--format github-annotations` automatically. + +**The result:** Developer Experience is unified. The error is surfaced exactly where the code was changed. The cognitive overhead of mapping a terminal line number back to a file in the IDE is eliminated. + +## Progressive Adoption (`--only`) + +Adopting a strict linter on a mature, undocumented legacy repository usually results in thousands of initial violations. Forcing a team to fix every broken link, missing alt text, and unused asset before merging a single PR is a failure of governance. It blocks adoption. + +The `--only` flag solves this by applying a destructive filter to the Zenzic analysis engine. It accepts a comma-separated list of Z-Codes and silently drops all findings that do not match. + +```bash +# Block PRs strictly on credential leaks and nothing else +uvx zenzic check all --ci --only Z201,Z204 +``` + +This is the mechanism for **Progressive Adoption**. Tech Leads can deploy Zenzic to block critical security regressions (credential leaks, path traversal) without breaking the build over structural warnings. As the documentation debt is paid down, the `--only` filter can be expanded or removed entirely to enforce the full rule matrix. + +## The End of Network Non-Determinism + +Traditional linters fail in CI environments due to rate-limiting and external link timeouts, introducing unacceptable non-determinism into the build pipeline. Zenzic eliminates this bottleneck entirely by replacing synchronous network requests with an asynchronous I/O architecture. + +Zenzic v0.10.0 ships with a new **Async Network Engine** built on `asyncio` and `httpx`, enabling concurrent validation of external links. To eradicate latency across repeated CI runs, we deployed **Atomic Local Caching** with a configurable 24-hour TTL, saving results safely to `.zenzic_cache/external_links.json`. + +Furthermore, the engine now features an **Anti-Overfetching Smart Fallback**. When external servers arbitrarily block `HEAD` requests (e.g., returning 403 or 405), Zenzic immediately falls back to a streaming `GET` request, safely aborting the connection before downloading the actual payload. Zero false positives. Zero network non-determinism. + +Hostile precision, zero fluff. Upgrade to v0.10.0 via the official `PythonWoods/zenzic-action` composite action or locally via `uv tool upgrade zenzic`. diff --git a/blog/tags.yml b/blog/tags.yml index c61c289..d3ebcbe 100644 --- a/blog/tags.yml +++ b/blog/tags.yml @@ -3,6 +3,11 @@ # # Zenzic Blog — Semantic Tag Registry +ci-cd: + label: "CI/CD" + permalink: /ci-cd + description: "Continuous Integration and Continuous Deployment integration guides and features." + release: label: "Release" permalink: /release diff --git a/changelogs/README.md b/changelogs/README.md index 0b62394..7ca3012 100644 --- a/changelogs/README.md +++ b/changelogs/README.md @@ -8,6 +8,7 @@ For active development notes, see [../CHANGELOG.md](../CHANGELOG.md). | Version | Period | Archive | |---------|--------|---------| -| v0.9.x | 2026-05-31 → active | [main CHANGELOG](../CHANGELOG.md) | +| v0.10.x | 2026-06-06 → active | [main CHANGELOG](../CHANGELOG.md) | +| v0.9.x | 2026-05-31 to 2026-06-05 | [v0.9.md](./v0.9.md) | | v0.8.x | — | [v0.8.md](./v0.8.md) | | v0.7.x | — | [v0.7.md](./v0.7.md) | diff --git a/changelogs/v0.9.md b/changelogs/v0.9.md index 17d741d..141cb22 100644 --- a/changelogs/v0.9.md +++ b/changelogs/v0.9.md @@ -1,8 +1,49 @@ -# Changelog Archive — v0.9.x +# Changelog Archive: v0.9.x -> **v0.9.x is the active minor line.** -> Release notes are maintained in the [main CHANGELOG](../CHANGELOG.md). -> This file will be populated when v0.10.0 ships and the v0.9.x minor closes. +## [0.9.2] - 2026-06-05 + +### Added + +- **Engine Guide — Supported Engine Versions table:** Added "Supported Engine Versions" section to `docs/reference/engines.mdx` (EN + IT) documenting the supported major-version line for each adapter: MkDocs `1.x`, Zensical `0.0.x`, Docusaurus `3.x`, Standalone (agnostic). Clarifies that version constraints apply to the config-file schema, not the installed engine binary. +- **Z109 EXTERNAL_LINK_BROKEN:** Documented Z109 external link finding code (EN + IT) representing broken external URLs. +- **Diátaxis Compliance Refactoring:** Restructured documentation portal for strict Diátaxis compliance (Batches 1-4), renaming example directories from `docs/how-to/examples/` to `docs/tutorials/examples/` to correctly separate tutorials from how-tos. +- **Resolved route collisions and sidebar ordering:** Restructured examples and sidebar configurations to resolve overlapping routes and optimize navigation. + +--- + +## [0.9.1] - 2026-06-02 + +### Added + +- Z-Code Gallery completion (EN + IT) aligned with the full release scope. +- New documentation pages and galleries for `Z107 CIRCULAR_ANCHOR` and `Z104 FILE_NOT_FOUND`. + +### Changed + +- **Repository-Relative Suppression Config:** Updated `.zenzic.toml` `per_file_ignores` and `directory_policies` to use strictly repository-relative keys (prefixed with `docs/` or `docs/it/`). +- **Strategic Navigation Exemption:** Added `directory_policies` exemption for `docs/how-to/examples/**` under `Z401` to prevent scoring penalties on example directories that intentionally lack index files. +- **Score Badge telemetry:** Stamped quality score badge inline in `README.md` and `README.it.md` to show a passing score of `96/100`. +- Hostile Precision UI standardization applied across release-facing documentation surfaces. +- Terminal documentation debt removed by normalizing legacy snippets and inconsistent command narratives. +- SVG asset governance aligned with ADR-037 compliance requirements. + +--- + +## [0.9.0] - 2026-05-31 + +### Added + +- Historical archive split for v0.8.x and v0.7.x release notes under `changelogs/`. +- `tutorials/examples.mdx` (EN + IT): full gallery of all 20 `zenzic lab` sandboxes with scenario matrix, exit-code column, and per-scenario prose. +- 15 new gallery sections covering z102, z103, z105, z108, z202, z204, z301, z302, z303, z402, z403, z501, z502, z503, z505. +- `finding-codes.mdx` (EN + IT): Z204 CLI output updated to `POLICY VIOLATION DETECTED` banner. +- `privacy-gate.mdx` (EN + IT): Exit Behavior section and `[core]` table-header fix. + +### Changed + +- Documentation for local gates now mirrors the real `just verify` recipe sequence (pre-commit hooks → pytest → strict audit → score stamp → freshness gate). +- Developers command matrix updated to remove obsolete preflight terminology. +- v0.8.x narratives archived; v0.9.0 sprint material moved to this entry. diff --git a/docs/how-to/configuration-strategy.mdx b/docs/how-to/configuration-strategy.mdx index 94ae123..6b22ed2 100644 --- a/docs/how-to/configuration-strategy.mdx +++ b/docs/how-to/configuration-strategy.mdx @@ -110,6 +110,15 @@ This is expected. To apply overrides in CI, write the file from a secret before --- +### Disable network cache in ephemeral environments + +Zenzic caches external link responses for 24 hours by default. In highly ephemeral environments (like certain Dockerized CI pipelines) where persisting `.zenzic_cache/` between runs is impossible or undesirable, you can disable the cache entirely to force synchronous network validation on every run. + +```toml title=".zenzic.toml" +[network] +cache_ttl_hours = 0 +``` + --- > For the full field specification, see [Configuration Reference](../reference/configuration-reference.mdx). diff --git a/docs/how-to/configure-ci-cd.mdx b/docs/how-to/configure-ci-cd.mdx index d325068..273ce34 100644 --- a/docs/how-to/configure-ci-cd.mdx +++ b/docs/how-to/configure-ci-cd.mdx @@ -115,8 +115,9 @@ jobs: - uses: actions/checkout@v6 - name: Lint documentation - - run: uvx zenzic check all --strict + # --ci automatically applies --strict and --format github-annotations + # for inline PR feedback + run: uvx zenzic check all --ci - name: Check references and credentials @@ -153,7 +154,7 @@ jobs: - name: Lint documentation - run: uvx zenzic check all --strict + run: uvx zenzic check all --ci - name: Check references and credentials @@ -198,7 +199,7 @@ jobs: uses: PythonWoods/zenzic-action@ with: - version: "0.9.2" # pin to a stable release + version: "0.10.0" # pin to a stable release format: sarif # emit SARIF for Code Scanning upload-sarif: "true" fail-on-error: "true" @@ -212,7 +213,9 @@ Security incidents (exit 2 and 3) are never suppressed by `fail-on-error: "false | Input | Default | Description | | :--- | :---: | :--- | | `version` | action pin | Zenzic version to install. Uses the pinned default declared in the action manifest; any explicit value uses `uvx "zenzic==X.Y.Z"`. **Pin in production.** | -| `format` | `sarif` | Output format: `text`, `json`, or `sarif`. Use `sarif` for GitHub Code Scanning. | +| `ci` | `false` | Run with `--ci` to enable `--strict` and inline GitHub PR annotations. Note: Not recommended when using `format: sarif` as annotations are handled by Code Scanning. | +| `only` | `""` | Comma-separated list of Z-Codes (e.g. "Z104,Z402") to restrict checks to specific issues. | +| `format` | `sarif` | Output format: `text`, `json`, `github-annotations`, or `sarif`. Use `sarif` for GitHub Code Scanning. | | `sarif-file` | `zenzic-results.sarif` | Path for the generated SARIF file (only when `format: sarif`). | | `upload-sarif` | `true` | Upload SARIF to GitHub Code Scanning via `github/codeql-action/upload-sarif` delegated by the wrapper. | | `strict` | `false` | Treat warnings as errors (passes `--strict` to Zenzic). | @@ -251,13 +254,29 @@ Slack notifications without re-parsing the SARIF file: id: zenzic uses: PythonWoods/zenzic-action@ with: - version: "0.9.2" + version: "0.10.0" - name: Post finding count run: echo "Zenzic found ${{ steps.zenzic.outputs.findings-count }} issues" ``` +### Progressive Adoption {#progressive-adoption} + +For large legacy repositories, fixing hundreds of warnings at once is impossible. The `only` parameter allows teams to adopt Zenzic progressively by enforcing only critical checks (e.g., Broken Links and Credential Leaks) while ignoring structural debt until the team is ready. + +By setting `ci: "true"`, the action natively injects the `--ci` flag under the hood, enabling inline PR annotations for the selected violations without requiring GitHub Code Scanning (SARIF) integration. + +```yaml title=".github/workflows/zenzic.yml" + - name: Zenzic Progressive Gate + uses: PythonWoods/zenzic-action@ + with: + version: "0.10.0" + ci: "true" # Native inline PR annotations (no SARIF required) + only: "Z101,Z201" # Gate ONLY fails on broken links and leaked secrets + fail-on-error: "true" +``` + :::warning[Security incidents are always fatal] `fail-on-error: "false"` suppresses exit 1 (quality findings) only. Exit 2 (credential scanner — credential detected) and exit 3 (path traversal guard — path traversal) are **never suppressible** by any input. @@ -301,7 +320,7 @@ jobs: - name: Run Zenzic and save baseline uses: PythonWoods/zenzic-action@ with: - version: "0.9.2" + version: "0.10.0" format: json # triggers .zenzic-score.json snapshot upload-sarif: "false" @@ -333,7 +352,7 @@ jobs: uses: PythonWoods/zenzic-action@ id: zenzic with: - version: "0.9.2" + version: "0.10.0" format: sarif upload-sarif: "true" diff-base: ".zenzic-baseline/.zenzic-score.json" @@ -381,7 +400,7 @@ jobs: - name: Sovereign Audit (suppressions bypassed) uses: PythonWoods/zenzic-action@ with: - version: "0.9.2" + version: "0.10.0" format: sarif upload-sarif: "true" audit: "true" # bypass all zenzic:ignore and per_file_ignores @@ -400,7 +419,7 @@ The `guard-scan: "true"` input runs `zenzic guard scan` as a standalone step **b - name: Run Zenzic Documentation Quality Gate uses: PythonWoods/zenzic-action@ with: - version: "0.9.2" + version: "0.10.0" guard-scan: "true" # zenzic guard scan runs before check all format: sarif upload-sarif: "true" diff --git a/docs/how-to/handle-technical-debt.mdx b/docs/how-to/handle-technical-debt.mdx index 113c82a..f77bfcd 100644 --- a/docs/how-to/handle-technical-debt.mdx +++ b/docs/how-to/handle-technical-debt.mdx @@ -133,6 +133,21 @@ This is by design. Security findings are facts, not style opinions. You cannot a --- +## Progressive Adoption via CLI Filtering {#progressive-adoption} + +When introducing Zenzic to a legacy repository, you may encounter hundreds of structural or stylistic warnings. Attempting to fix everything at once often stalls adoption. + +The new `--only` flag (introduced in v0.10.0) allows teams to adopt Zenzic progressively without blocking CI. You can enforce only the most critical rules (such as credential leaks and broken links) and systematically add more codes as the technical debt is paid down. + +```bash +# Start by enforcing only Security Gates and Broken Links +zenzic check all --only Z201,Z202,Z204,Z101,Z104 +``` + +As your team resolves the structural debt, you can progressively expand the `--only` list until the repository is ready for a full, unfiltered `zenzic check all`. This allows you to secure the most critical aspects of your documentation immediately. + +--- + ## Resolving Discrepancies with Build Engines {#build-engine-discrepancies} If Zenzic reports a broken link that your build engine accepts, it is typically due to frontmatter routing overrides. Build engines like Docusaurus allow authors to override a file's canonical URL using the `slug:` frontmatter key. Zenzic strictly enforces that links target the exact resolved URL (the slug), rather than the physical file path. To fix the discrepancy, update the broken link to match the overridden slug. diff --git a/docs/how-to/install.mdx b/docs/how-to/install.mdx index e15b783..ac433cb 100644 --- a/docs/how-to/install.mdx +++ b/docs/how-to/install.mdx @@ -50,6 +50,20 @@ your system Python clean. +### Execute from GitHub (No installation) {#install-github} + +If you want to run Zenzic against a repository without installing it locally, you can execute it directly from the GitHub repository using `uvx`. This is useful for testing Zenzic on a project or using it as a distributed CLI tool. + +```bash +uvx --from git+https://github.com/PythonWoods/zenzic zenzic . +``` + +You can also pin to a specific version tag for deterministic execution: + +```bash +uvx --from git+https://github.com/PythonWoods/zenzic@ zenzic . +``` + ### Global tool — available in every project {#install-global} @@ -181,6 +195,10 @@ fail_under = 70 # establish an initial quality floor See the [Configuration Reference](../reference/index.mdx) for the full field list. +:::tip[Git Ignore] +Add `.zenzic_cache/` to your repository's `.gitignore` to prevent committing the local network validation cache. +::: + ### 3. Check — run continuously {#check} With the baseline established, run Zenzic on every commit and pull request: diff --git a/docs/reference/cli.mdx b/docs/reference/cli.mdx index 70deb88..b822220 100644 --- a/docs/reference/cli.mdx +++ b/docs/reference/cli.mdx @@ -31,6 +31,9 @@ zenzic check all # Run all checks zenzic check all --audit # Sovereign Audit: ignore inline + per-file suppressions zenzic check all --strict # Also validate external URLs; treat warnings as errors zenzic check all --format json # Machine-readable output +zenzic check all --format github-annotations # GitHub Actions annotations format +zenzic check all --ci # CI shorthand: sets --strict and --format github-annotations +zenzic check all --only Z104,Z101 # Filter findings to only output specific Z-Codes 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 @@ -112,6 +115,29 @@ The `--strict` flag enforces rigorous validation: for link checking, it validate You can also set `strict = true` in `.zenzic.toml` to make it the permanent default. +### `--ci` + +`--ci` is a convenience shorthand designed specifically for GitHub Actions pipelines. It forces two behaviors simultaneously: +1. Sets `strict = true` (warnings promote to errors). +2. Sets `--format github-annotations` (if no other format is specified). + +This flag bypasses `ZenzicReporter` completely, outputting raw `::error::` strings that GitHub Actions parses natively to create inline annotations on pull requests. + +```bash +zenzic check all --ci +``` + +### `--only` + +`--only` applies a destructive engine-level filter to the Zenzic findings pipeline. It accepts a comma-separated list of Z-Codes. Any findings that do not match the specified codes are silently discarded *before* being processed by the formatter. + +Use this to run highly targeted, isolated checks—for example, if you only want to scan for broken links (`Z104`) and orphans (`Z402`) without running the rest of the validations, or if you want to silence everything except credential leaks (`Z201`). + +```bash +zenzic check all --only Z104,Z402 +zenzic check links --only Z101,Z104 +``` + ### `--exit-zero` Always exits with code `0` even when issues are found. All findings are still printed and diff --git a/docs/reference/configuration-reference.mdx b/docs/reference/configuration-reference.mdx index da9a811..30ff0a3 100644 --- a/docs/reference/configuration-reference.mdx +++ b/docs/reference/configuration-reference.mdx @@ -381,6 +381,29 @@ included_file_patterns = ["api.generated.md"] --- +--- + +## Network Settings {#network-settings} + +The `[network]` section controls external network resolution behaviors, specifically atomic local caching. + +### `cache_ttl_hours` {#cache-ttl-hours} + +| | | +| :--- | :--- | +| **Type** | `int` | +| **Default** | `24` | +| **Section** | `[network]` | + +Time-To-Live (in hours) for the atomic local cache of external link validation (`.zenzic_cache/external_links.json`). Set to `0` to completely disable caching and force synchronous network validation for every run. + +```toml +[network] +cache_ttl_hours = 24 +``` + +--- + ## Build Context {#build-context} The `[build_context]` table tells Zenzic which documentation engine produced the site and how to resolve locale-specific paths. diff --git a/docs/reference/engines.mdx b/docs/reference/engines.mdx index c1ca000..d6598fb 100644 --- a/docs/reference/engines.mdx +++ b/docs/reference/engines.mdx @@ -110,9 +110,9 @@ build pipeline. This means: from Zenzic's view. - **Plugin-generated nav** — plugins that mutate the nav at runtime (e.g. `mkdocs-awesome-pages`, - `mkdocs-literate-nav`) produce a navigation tree that Zenzic never sees. Pages included only by these plugins will be reported as orphans. + *Technical Note on `mkdocs-awesome-pages`: Zenzic's static adapter does not read `.pages` files. If you use `.pages` files to define navigation, Zenzic will not see those pages as reachable and will flag them as orphans unless they are explicitly linked from other reachable pages.* - **Macros** — `mkdocs-macros-plugin` (Jinja2 templates in Markdown) is not evaluated. diff --git a/docs/reference/zenzic-action.mdx b/docs/reference/zenzic-action.mdx index 9d437c9..b9ae7d5 100644 --- a/docs/reference/zenzic-action.mdx +++ b/docs/reference/zenzic-action.mdx @@ -24,6 +24,8 @@ Source: [github.com/PythonWoods/zenzic-action](https://github.com/PythonWoods/ze | `sarif-file` | `zenzic-results.sarif` | No | SARIF output path. Must be a **relative** path inside the workspace. Absolute paths and `..` traversal sequences are rejected by the wrapper. | | `upload-sarif` | `true` | No | Upload SARIF to GitHub Code Scanning. Requires `security-events: write` permission. | | `strict` | `false` | No | Treat warnings as errors — promotes all `warning`-severity findings to `error`. | +| `ci` | `false` | No | Run with `--ci` to enable `--strict` and inline GitHub PR annotations. | +| `only` | `""` | No | Comma-separated list of Z-Codes to filter. Enables Progressive Adoption. | | `fail-on-error` | `true` | No | Fail the workflow step on exit 1 (quality findings). Does **not** suppress exit 2 or 3. | | `config-file` | *(auto)* | No | Explicit path to a `.zenzic.toml` config file. Auto-discovers `.zenzic.toml` → `.github/.zenzic.toml` when omitted. | | `audit` | `false` | No | Sovereign audit mode — bypasses all `zenzic:ignore` inline comments and `governance.per_file_ignores` entries. Reveals the true, unfiltered documentation state. | diff --git a/docs/tutorials/examples/z4xx-topology/z401-missing-directory-index.mdx b/docs/tutorials/examples/z4xx-topology/z401-missing-directory-index.mdx index 2f723f8..7122876 100644 --- a/docs/tutorials/examples/z4xx-topology/z401-missing-directory-index.mdx +++ b/docs/tutorials/examples/z4xx-topology/z401-missing-directory-index.mdx @@ -78,6 +78,8 @@ Documentation engines that use directory-style URLs (e.g., `/guide/` instead of (or `index.mdx`) as its landing page. Without one, the build engine may silently omit the directory URL or return a 404: +> **Standalone Mode:** When using the `standalone` engine, Zenzic accepts both `index.md` and `README.md` as valid directory indices, adapting natively to standard GitHub/GitLab repository structures. + - **Scan Type:** `Structure Validator (zensical engine)` - **Severity:** `Info` - **Impact:** Deducts **2.0 DQS points** (navigation category, weight 0.25). diff --git a/docs/tutorials/examples/z5xx-content/z501-placeholder.mdx b/docs/tutorials/examples/z5xx-content/z501-placeholder.mdx index 7c81200..2dd1613 100644 --- a/docs/tutorials/examples/z5xx-content/z501-placeholder.mdx +++ b/docs/tutorials/examples/z5xx-content/z501-placeholder.mdx @@ -145,7 +145,9 @@ Exit code: `0` The `Z501` finding indicates a **PLACEHOLDER** issue. -This error or warning is raised by Zenzic when the document contains placeholder patterns like 'TODO', 'FIXME', 'LOREM IPSUM', or generic boilerplate strings. This checks if draft text leaked into production docs. In this specific example: +This error or warning is raised by Zenzic when the document contains placeholder patterns like 'TODO', 'FIXME', 'LOREM IPSUM', or generic boilerplate strings. This checks if draft text leaked into production docs. By default, Zenzic is ultra-conservative: it uses explicit word boundaries (`\bTODO\b`, `\bFIXME\b`) to prevent the Scunthorpe Problem (e.g., flagging the word "autodome" because it contains "todo"). + +In this specific example: - **Scan Type:** `Content Guard` - **Severity:** `Warning` - **Impact:** Placeholder text indicates incomplete documentation and results in a DQS deduction of 2.0 points. diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 20d7840..4521bc6 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -75,7 +75,7 @@ const config: Config = { lastVersion: 'current', versions: { current: { - label: '0.9.2', + label: '0.10.0', badge: false, banner: 'none', }, @@ -239,7 +239,7 @@ const config: Config = { ], }, ], - copyright: `© ${new Date().getFullYear()} PythonWoods · Zenzic v0.9.2 · Engineered with precision by PythonWoods in Italy 🇮🇹`, + copyright: `© ${new Date().getFullYear()} PythonWoods · Zenzic v0.10.0 · Engineered with precision by PythonWoods in Italy 🇮🇹`, }, prism: { theme: prismThemes.github, diff --git a/i18n/en/code.json b/i18n/en/code.json index 7fed4fa..416a457 100644 --- a/i18n/en/code.json +++ b/i18n/en/code.json @@ -43,7 +43,7 @@ "message": "Brand obsolescence" }, "homepage.hero.badge": { - "message": "v0.9.2", + "message": "v0.10.0", "description": "Wait release version badge" }, "enterprise.section.sub": { diff --git a/i18n/it/code.json b/i18n/it/code.json index e203186..fde2eb3 100644 --- a/i18n/it/code.json +++ b/i18n/it/code.json @@ -379,7 +379,7 @@ "message": "Marchio obsoleto" }, "homepage.hero.badge": { - "message": "v0.9.2", + "message": "v0.10.0", "description": "Wait release version badge" }, "homepage.hero.title": { diff --git a/i18n/it/docusaurus-plugin-content-docs/current.json b/i18n/it/docusaurus-plugin-content-docs/current.json index 9c993f3..2fbc9b7 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current.json +++ b/i18n/it/docusaurus-plugin-content-docs/current.json @@ -1,6 +1,6 @@ { "version.label": { - "message": "0.9.2", + "message": "0.10.0", "description": "The label for version current" }, "sidebar.tutorialSidebar.category.User Guide": { diff --git a/i18n/it/docusaurus-plugin-content-docs/current/how-to/configuration-strategy.mdx b/i18n/it/docusaurus-plugin-content-docs/current/how-to/configuration-strategy.mdx index 03b849c..39f4aa5 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/how-to/configuration-strategy.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/how-to/configuration-strategy.mdx @@ -97,6 +97,15 @@ Questo è previsto. Per applicare gli override in CI, scrivi il file da un secre --- +### Disabilitare la cache di rete in ambienti effimeri + +Zenzic fa caching delle risposte dei link esterni per 24 ore di default. In ambienti altamente effimeri (come certe pipeline CI dockerizzate) dove la persistenza di `.zenzic_cache/` tra le esecuzioni è impossibile o indesiderata, puoi disabilitare completamente la cache per forzare la validazione sincrona di rete ad ogni run. + +```toml title=".zenzic.toml" +[network] +cache_ttl_hours = 0 +``` + --- > Per la specifica completa dei campi, vedi [Configuration Reference](../reference/configuration-reference.mdx). diff --git a/i18n/it/docusaurus-plugin-content-docs/current/how-to/configure-ci-cd.mdx b/i18n/it/docusaurus-plugin-content-docs/current/how-to/configure-ci-cd.mdx index 6465b7c..0a50b76 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/how-to/configure-ci-cd.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/how-to/configure-ci-cd.mdx @@ -115,8 +115,9 @@ jobs: - uses: actions/checkout@v6 - name: Lint documentazione - - run: uvx zenzic check all --strict + # --ci applica automaticamente --strict e --format github-annotations + # per feedback inline sulle PR + run: uvx zenzic check all --ci - name: Controllo riferimenti e credential scanner @@ -153,7 +154,7 @@ jobs: - name: Lint documentazione - run: uvx zenzic check all --strict + run: uvx zenzic check all --ci - name: Controllo riferimenti e credential scanner @@ -198,7 +199,7 @@ jobs: uses: PythonWoods/zenzic-action@ with: - version: "0.9.2" # fissa a una release stabile + version: "0.10.0" # fissa a una release stabile format: sarif # emetti SARIF per Code Scanning upload-sarif: "true" fail-on-error: "true" @@ -212,7 +213,9 @@ il [Contratto Exit Code](https://github.com/PythonWoods/zenzic-action) è applic | Input | Default | Descrizione | | :--- | :---: | :--- | | `version` | pin action | Versione di Zenzic da installare. Usa il pin di default dichiarato nel manifest dell'action; qualsiasi valore esplicito usa `uvx "zenzic==X.Y.Z"`. **Fissa in produzione.** | -| `format` | `sarif` | Formato di output: `text`, `json` o `sarif`. Usa `sarif` per GitHub Code Scanning. | +| `ci` | `false` | Esegue con `--ci` per abilitare `--strict` e le annotazioni inline sulle PR GitHub. Nota: sconsigliato quando si usa `format: sarif` poiché le annotazioni sono gestite dal Code Scanning. | +| `only` | `""` | Lista separata da virgole di Codici Z (es. "Z104,Z402") per limitare i controlli a problemi specifici. | +| `format` | `sarif` | Formato di output: `text`, `json`, `github-annotations` o `sarif`. Usa `sarif` per GitHub Code Scanning. | | `sarif-file` | `zenzic-results.sarif` | Percorso del file SARIF generato (solo quando `format: sarif`). | | `upload-sarif` | `true` | Carica il SARIF in GitHub Code Scanning via `github/codeql-action/upload-sarif` delegato dal wrapper. | | `strict` | `false` | Tratta i warning come errori (passa `--strict` a Zenzic). | @@ -251,13 +254,29 @@ o notifiche Slack senza dover rileggere il file SARIF: id: zenzic uses: PythonWoods/zenzic-action@ with: - version: "0.9.2" + version: "0.10.0" - name: Mostra conteggio finding run: echo "Zenzic ha trovato ${{ steps.zenzic.outputs.findings-count }} problemi" ``` +### Adozione Progressiva (Progressive Adoption) {#progressive-adoption} + +Per grandi repository legacy, correggere centinaia di warning in un colpo solo è impossibile. Il parametro `only` permette ai team di adottare Zenzic in modo progressivo, applicando solo controlli critici (es. Link Rotti e Leak di Credenziali) e ignorando il debito strutturale finché il team non è pronto. + +Impostando `ci: "true"`, l'action inietta nativamente il flag `--ci` sotto il cofano, abilitando le annotazioni inline sulle PR per le violazioni selezionate senza richiedere l'integrazione con GitHub Code Scanning (SARIF). + +```yaml title=".github/workflows/zenzic.yml" + - name: Zenzic Progressive Gate + uses: PythonWoods/zenzic-action@ + with: + version: "0.10.0" + ci: "true" # Annotazioni PR native (non richiede SARIF) + only: "Z101,Z201" # Il Gate fallisce SOLO per link rotti e segreti esposti + fail-on-error: "true" +``` + :::warning[Gli incidenti di sicurezza sono sempre fatali] `fail-on-error: "false"` sopprime solo exit 1 (finding di qualità). Exit 2 (Credential scanner — credenziale rilevata) e exit 3 (path traversal guard — path traversal) **non sono mai sopprimibili** con alcun input. @@ -301,7 +320,7 @@ jobs: - name: Esegui Zenzic e salva il baseline uses: PythonWoods/zenzic-action@ with: - version: "0.9.2" + version: "0.10.0" format: json # genera lo snapshot .zenzic-score.json upload-sarif: "false" @@ -333,7 +352,7 @@ jobs: uses: PythonWoods/zenzic-action@ id: zenzic with: - version: "0.9.2" + version: "0.10.0" format: sarif upload-sarif: "true" diff-base: ".zenzic-baseline/.zenzic-score.json" @@ -381,7 +400,7 @@ jobs: - name: Sovereign Audit (soppressioni bypassate) uses: PythonWoods/zenzic-action@ with: - version: "0.9.2" + version: "0.10.0" format: sarif upload-sarif: "true" audit: "true" # bypassa tutti i zenzic:ignore e per_file_ignores @@ -400,7 +419,7 @@ L'input `guard-scan: "true"` esegue `zenzic guard scan` come step standalone **p - name: Run Zenzic Documentation Quality Gate uses: PythonWoods/zenzic-action@ with: - version: "0.9.2" + version: "0.10.0" guard-scan: "true" # zenzic guard scan viene eseguito prima di check all format: sarif upload-sarif: "true" diff --git a/i18n/it/docusaurus-plugin-content-docs/current/how-to/handle-technical-debt.mdx b/i18n/it/docusaurus-plugin-content-docs/current/how-to/handle-technical-debt.mdx index 3659985..a63bfd6 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/how-to/handle-technical-debt.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/how-to/handle-technical-debt.mdx @@ -145,6 +145,21 @@ assumerti la responsabilità di una perdita di credenziali e chiamarla eccezione --- +## Progressive Adoption via CLI Filtering {#progressive-adoption} + +Quando si introduce Zenzic in un repository legacy, potresti incontrare centinaia di warning strutturali o stilistici. Cercare di correggere tutto in una volta spesso blocca l'adozione. + +Il nuovo flag `--only` (introdotto in v0.10.0) permette ai team di adottare Zenzic progressivamente senza bloccare la CI. Puoi far rispettare solo le regole più critiche (come i leak di credenziali e i link rotti) e aggiungere sistematicamente più codici man mano che il technical debt viene ripagato. + +```bash +# Inizia imponendo solo i Security Gate e i Link Rotti +zenzic check all --only Z201,Z202,Z204,Z101,Z104 +``` + +Man mano che il tuo team risolve il debito strutturale, puoi espandere progressivamente la lista `--only` finché il repository non è pronto per un `zenzic check all` completo e non filtrato. Questo ti permette di mettere in sicurezza immediatamente gli aspetti più critici della tua documentazione. + +--- + ## Riferimento {#reference} - [Politica di Soppressione](../reference/suppression-policy.mdx) — Riferimento completo per tutti e tre i livelli di soppressione. diff --git a/i18n/it/docusaurus-plugin-content-docs/current/how-to/install.mdx b/i18n/it/docusaurus-plugin-content-docs/current/how-to/install.mdx index a282a72..cfb572e 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/how-to/install.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/how-to/install.mdx @@ -47,6 +47,20 @@ mantenere pulito il Python di sistema. +### Eseguire da GitHub (Nessuna installazione) {#install-github} + +Se vuoi eseguire Zenzic su un repository senza installarlo localmente, puoi eseguirlo direttamente dal repository GitHub utilizzando `uvx`. Questo è utile per testare Zenzic su un progetto o per usarlo come CLI temporanea e distribuita. + +```bash +uvx --from git+https://github.com/PythonWoods/zenzic zenzic . +``` + +Puoi anche fissare un tag di versione specifico per un'esecuzione deterministica: + +```bash +uvx --from git+https://github.com/PythonWoods/zenzic@ zenzic . +``` + ### Strumento globale — disponibile in ogni progetto {#install-global} @@ -178,6 +192,10 @@ fail_under = 70 # stabilisce un quality floor iniziale Consulta la [Guida alla Configurazione](../reference/index.mdx) per l'elenco completo dei campi. +:::tip[Git Ignore] +Aggiungi `.zenzic_cache/` al file `.gitignore` del tuo repository per evitare di committare la cache locale della validazione di rete. +::: + ### 3. Check — esegui in modo continuativo {#check} Con il baseline stabilito, esegui Zenzic su ogni commit e pull request: diff --git a/i18n/it/docusaurus-plugin-content-docs/current/reference/cli.mdx b/i18n/it/docusaurus-plugin-content-docs/current/reference/cli.mdx index d3d0364..4db29aa 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/reference/cli.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/reference/cli.mdx @@ -29,6 +29,9 @@ zenzic check all # Esegue tutti i controlli zenzic check all --audit # Audit Sovrano: ignora soppressioni inline + per-file zenzic check all --strict # Valida anche gli URL esterni; tratta i warning come errori zenzic check all --format json # Output machine-readable +zenzic check all --format github-annotations # Formato annotazioni GitHub Actions +zenzic check all --ci # Shorthand CI: imposta --strict e --format github-annotations +zenzic check all --only Z104,Z101 # Filtra i finding per produrre solo specifici codici Z 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 @@ -108,6 +111,29 @@ log CI sia inequivocabile anche quando gli stessi finding sarebbero altrimenti n Puoi anche impostare `strict = true` in `.zenzic.toml` per renderlo il default permanente. +### `--ci` + +`--ci` è un comodo shorthand progettato specificamente per le pipeline GitHub Actions. Forza due comportamenti simultaneamente: +1. Imposta `strict = true` (promuove i warning ad errori bloccanti). +2. Imposta `--format github-annotations` (se non è specificato alcun altro formato). + +Questo flag bypassa completamente `ZenzicReporter`, emettendo stringhe grezze `::error::` che GitHub Actions analizza nativamente per creare annotazioni inline sulle pull request. + +```bash +zenzic check all --ci +``` + +### `--only` + +`--only` applica un filtro distruttivo a livello engine per i finding Zenzic. Accetta una lista di Codici Z separata da virgole. Qualsiasi finding che non corrisponde ai codici specificati viene scartato silenziosamente *prima* di essere elaborato dal formatter. + +Usalo per eseguire controlli altamente mirati e isolati — per esempio, se vuoi scannerizzare solo i link rotti (`Z104`) e gli orfani (`Z402`) senza eseguire il resto delle validazioni, o se vuoi silenziare tutto ad eccezione dei leak di credenziali (`Z201`). + +```bash +zenzic check all --only Z104,Z402 +zenzic check links --only Z101,Z104 +``` + ### `--exit-zero` Esce sempre con codice `0` anche quando vengono trovati problemi. Tutti i problemi vengono diff --git a/i18n/it/docusaurus-plugin-content-docs/current/reference/configuration-reference.mdx b/i18n/it/docusaurus-plugin-content-docs/current/reference/configuration-reference.mdx index 391a461..b217348 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/reference/configuration-reference.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/reference/configuration-reference.mdx @@ -364,6 +364,27 @@ Non aggiungere mai un intero dominio come esclusione (es. `"https://zenzic.dev/" --- +--- + +## Impostazioni di Rete {#network-settings} + +La sezione `[network]` controlla i comportamenti di risoluzione di rete esterna, nello specifico il caching locale atomico. + +### `cache_ttl_hours` {#cache-ttl-hours} + +| Campo | Tipo | Predefinito | Descrizione | +| :--- | :--- | :--- | :--- | +| `cache_ttl_hours` | `int` | `24` | Time-To-Live (in ore) per la cache atomica locale | + +Time-To-Live (in ore) per la cache locale atomica della validazione dei link esterni (`.zenzic_cache/external_links.json`). Imposta a `0` per disabilitare completamente la cache e forzare la validazione di rete per ogni esecuzione. + +```toml +[network] +cache_ttl_hours = 24 +``` + +--- + ## Contesto di build {#build-context} ```toml diff --git a/i18n/it/docusaurus-plugin-content-docs/current/reference/engines.mdx b/i18n/it/docusaurus-plugin-content-docs/current/reference/engines.mdx index ae1d78b..89714dd 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/reference/engines.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/reference/engines.mdx @@ -113,10 +113,10 @@ build di MkDocs. Questo significa: valori saranno assenti dalla visione di Zenzic. - **Nav generata dai plugin** — plugin che mutano la nav a runtime (es. - `mkdocs-awesome-pages`, `mkdocs-literate-nav`) producono un albero di navigazione che Zenzic non vede mai. Le pagine incluse solo da questi plugin vengono segnalate come orfane. + *Nota Tecnica su `mkdocs-awesome-pages`: L'adapter statico di Zenzic non legge i file `.pages`. Se si utilizzano i file `.pages` per definire la navigazione, Zenzic non vedrà quelle pagine come raggiungibili e le segnalerà come orfane a meno che non siano esplicitamente linkate da altre pagine raggiungibili.* - **Macro** — `mkdocs-macros-plugin` (template Jinja2 in Markdown) non viene diff --git a/i18n/it/docusaurus-plugin-content-docs/current/reference/zenzic-action.mdx b/i18n/it/docusaurus-plugin-content-docs/current/reference/zenzic-action.mdx index a54a7db..7510271 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/reference/zenzic-action.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/reference/zenzic-action.mdx @@ -29,6 +29,8 @@ Sorgente: [github.com/PythonWoods/zenzic-action](https://github.com/PythonWoods/ | `sarif-file` | `zenzic-results.sarif` | No | Percorso di output SARIF. Deve essere un percorso **relativo** all'interno del workspace. I percorsi assoluti e le sequenze di traversal `..` vengono rifiutati dal wrapper. | | `upload-sarif` | `true` | No | Carica il SARIF in GitHub Code Scanning. Richiede il permesso `security-events: write`. | | `strict` | `false` | No | Tratta i warning come errori — promuove tutti i finding con severità `warning` ad `error`. | +| `ci` | `false` | No | Esegue con `--ci` per abilitare `--strict` e le annotazioni inline sulle PR GitHub. | +| `only` | `""` | No | Lista separata da virgole di Codici Z da filtrare. Abilita la Progressive Adoption. | | `fail-on-error` | `true` | No | Fa fallire lo step del workflow su exit 1 (finding di qualità). **Non** sopprime exit 2 o 3. | | `config-file` | *(auto)* | No | Percorso esplicito a un file di configurazione `.zenzic.toml`. Auto-scopre `.zenzic.toml` → `.github/.zenzic.toml` se omesso. | | `audit` | `false` | No | Modalità sovereign audit — bypassa tutti i commenti `zenzic:ignore` inline e tutte le voci `governance.per_file_ignores`. Rivela lo stato reale e non filtrato della documentazione. | diff --git a/i18n/it/docusaurus-plugin-content-docs/current/tutorials/examples/z4xx-topology/z401-missing-directory-index.mdx b/i18n/it/docusaurus-plugin-content-docs/current/tutorials/examples/z4xx-topology/z401-missing-directory-index.mdx index 693af0b..74afae0 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/tutorials/examples/z4xx-topology/z401-missing-directory-index.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/tutorials/examples/z4xx-topology/z401-missing-directory-index.mdx @@ -78,6 +78,8 @@ di `/guide.html`) richiedono che ogni directory navigabile abbia un `index.md` (o `index.mdx`) come pagina di atterraggio. Senza di esso, il motore di build può silenziosamente omettere l'URL della directory o restituire un 404: +> **Modalità Standalone:** Quando si utilizza l'engine `standalone`, Zenzic accetta sia `index.md` che `README.md` come indici di directory validi, adattandosi nativamente alle strutture standard dei repository GitHub/GitLab. + - **Tipo di scansione:** `Structure Validator (engine zensical)` - **Severità:** `Info` - **Impatto:** Deduce **2.0 punti DQS** (categoria navigazione, peso 0.25). diff --git a/i18n/it/docusaurus-plugin-content-docs/current/tutorials/examples/z5xx-content/z501-placeholder.mdx b/i18n/it/docusaurus-plugin-content-docs/current/tutorials/examples/z5xx-content/z501-placeholder.mdx index 04aba12..80d4f3e 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/tutorials/examples/z5xx-content/z501-placeholder.mdx +++ b/i18n/it/docusaurus-plugin-content-docs/current/tutorials/examples/z5xx-content/z501-placeholder.mdx @@ -145,7 +145,9 @@ Exit code: `0` Il codice di errore `Z501` indica un problema di tipo **PLACEHOLDER**. -Questo errore o avviso viene generato da Zenzic quando il documento contiene pattern di testo segnaposto come 'TODO', 'FIXME', 'LOREM IPSUM' o stringhe boilerplate generiche. Questo verifica che bozze non vengano pubblicate per errore. In questo esempio specifico: +Questo errore o avviso viene generato da Zenzic quando il documento contiene pattern di testo segnaposto come 'TODO', 'FIXME', 'LOREM IPSUM' o stringhe boilerplate generiche. Questo verifica che bozze non vengano pubblicate per errore. Di default, Zenzic è ultra-conservativo: usa i limiti di parola espliciti (`\bTODO\b`, `\bFIXME\b`) per prevenire il Problema di Scunthorpe (es. flaggare la parola "autodome" perché contiene "todo"). + +In questo esempio specifico: - **Tipo di Scansione:** `Content Guard` - **Severità:** `Warning` - **Impatto:** Il testo segnaposto indica una documentazione incompleta e comporta una detrazione DQS di 2.0 punti. diff --git a/package-lock.json b/package-lock.json index 9857cbb..bad9a3d 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "zenzic-doc", - "version": "0.9.2", + "version": "0.10.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "zenzic-doc", - "version": "0.9.2", + "version": "0.10.0", "dependencies": { "@docusaurus/core": "3.10.1", "@docusaurus/faster": "3.10.1", diff --git a/package.json b/package.json index 2ca2b7b..60bd27e 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "zenzic-doc", - "version": "0.9.2", + "version": "0.10.0", "private": true, "scripts": { "docusaurus": "docusaurus", diff --git a/src/components/Homepage/Features.tsx b/src/components/Homepage/Features.tsx index 216948e..05113cf 100644 --- a/src/components/Homepage/Features.tsx +++ b/src/components/Homepage/Features.tsx @@ -18,7 +18,7 @@ function TerminalPreview(): React.JSX.Element { - zenzic check all · v0.9.2 + zenzic check all · v0.10.0 {/* Output body */} diff --git a/src/components/Homepage/Hero.tsx b/src/components/Homepage/Hero.tsx index 8cfbc2a..3f17107 100644 --- a/src/components/Homepage/Hero.tsx +++ b/src/components/Homepage/Hero.tsx @@ -39,7 +39,7 @@ export default function Hero(): React.JSX.Element {
- v0.9.2 + v0.10.0

diff --git a/static/assets/brand/zenzic-brand-system.html b/static/assets/brand/zenzic-brand-system.html index de10bd3..3464d55 100644 --- a/static/assets/brand/zenzic-brand-system.html +++ b/static/assets/brand/zenzic-brand-system.html @@ -549,7 +549,7 @@

Code / UI · JetBrains Mono

-

Markdown static analyzer & credential scanner
uvx zenzic check all ./docs
v0.9.2 · exit 0

+

Markdown static analyzer & credential scanner
uvx zenzic check all ./docs
v0.10.0 · exit 0

@@ -711,7 +711,7 @@

CLI Output — Color Mapping

- ▮ ZENZIC v0.9.2
+ ▮ ZENZIC v0.10.0
✨ All statically-detectable links, credentials, and references verified.
⚠ WARNING docs/guide.md:14
✗ ERROR docs/api.md:88