feat(core): release v0.6.1 'Obsidian Glass' stable#69
Merged
PythonWoods-Dev merged 13 commits intomainfrom Apr 21, 2026
Merged
Conversation
Consolidates the v0.6.1 series, establishing Zenzic as a truly engine-agnostic documentation linter. This stable release bridges the gap between MkDocs and Zensical, while providing enterprise-grade support for Docusaurus v3. Key Features: - Zensical Transparent Proxy: native fallback to mkdocs.yml when zensical.toml is absent. - Docusaurus v3 Multi-versioning: support for versioned_docs/ and versions.json. - Path Resolution: @site/ alias support for Docusaurus project-relative links. - Offline Mode: --offline flag to force flat .html URL structure (ignoring directory slugs). - Sentinel Banner: transparent UI notifications for proxy and offline states. Stability & Compliance: - Fixed Docusaurus routeBasePath default to match official engine behavior (/docs/). - Full REUSE 3.3 compliance and metadata synchronization (CITATION.cff, pyproject.toml). - Bilingual (EN/IT) changelog and readme parity. - Resolved all linting violations via ruff hardening. Adheres to Zenzic Pillars: Lint the Source, No Subprocesses, Pure Functions First.
This commit marks the completion of the Guardians of Quality audit,
realigning the framework with official engine specifications.
Key Structural Improvements:
- Docusaurus Adapter: Fixed 'latest' version mapping to exclude URL prefixes.
- Docusaurus Adapter: Absolute slugs now correctly append to routeBasePath.
- Docusaurus Adapter: Implemented Smart Collapsing for README.md and {Folder}.md.
- Resolver: Native support for @site/ alias resolution across all adapters.
- Offline Mode: Global --offline flag for flat .html URL generation.
- Zensical Proxy: Automated bridge for mkdocs.yml compatibility.
Quality & Metadata:
- Updated 1,126 tests; added docusaurus_truth.py with official spec-tests.
- Synchronized EN/IT CHANGELOGs, READMEs, and CITATION.cff.
- Full REUSE 3.3 compliance and pre-commit hardening.
The Safe Harbor is now aligned with Docusaurus v3, MkDocs, and Zensical.
- README.md: fix [docs-cicd] → /docs/guides/ci-cd/ and [docs-arch] → /docs/internals/architecture-overview/ - CONTRIBUTING.md / CONTRIBUTING.it.md: fix ADR 003 link path (003-discovery-logic → discovery-logic/) - README.it.md: fix six reference-link definitions using incorrect /docs/it/ prefix (correct Docusaurus locale pattern: /it/docs/) - pyproject.toml: add trailing slash to Documentation URL; replace non-existent /docs/changelog with canonical GitHub CHANGELOG
…adapters
Extends the BaseAdapter protocol with a new discovery-phase method:
provides_index(directory_path: Path) -> bool
Each adapter implements engine-specific index-detection logic:
- DocusaurusAdapter: checks index.md/mdx, README.md/mdx; reads
_category_.json for "link": {"type": "generated-index"}
- MkDocsAdapter: checks index.md or README.md
- ZensicalAdapter: checks index.md
- ZensicalLegacyProxy: delegates to inner MkDocsAdapter
- VanillaAdapter: checks index.md
This is the only BaseAdapter method permitted to perform disk I/O
(Path.exists()). It is called once per directory during the discovery
phase — never inside per-link or per-file hot loops (Core Law 1).
Part of the Directory Index Integrity feature (MISSING_DIRECTORY_INDEX).
New public function that identifies documentation subdirectories
containing .md/.mdx source files but no engine-provided landing page:
find_missing_directory_indices(
docs_root, exclusion_manager, *, repo_root, config
) -> list[Path]
Implementation notes:
- Resolves the active adapter via get_adapter()
- Discovers candidate directories through walk_files() with the
mandatory LayeredExclusionManager (Core Law 3)
- docs_root itself is excluded — only subdirectories are checked
- Calls adapter.provides_index() once per candidate directory
- Returns paths relative to docs_root, sorted lexicographically
- Short-circuits on empty docs tree (returns [] immediately)
No I/O occurs inside the walk loop beyond the single provides_index()
call per directory (Core Law 1 preserved).
Part of the Directory Index Integrity feature (MISSING_DIRECTORY_INDEX).
- Import find_missing_directory_indices from scanner - Add directory_index_issues: list[Path] field to _AllCheckResults (not included in failed property — info-only, non-blocking) - Call find_missing_directory_indices() in _collect_all_results() - Convert results to Finding(code='MISSING_DIRECTORY_INDEX', severity='info') in _to_findings() - Visible with zenzic check all --show-info; never affects exit code Closes the Directory Index Integrity feature loop.
Add MISSING_DIRECTORY_INDEX finding and provides_index() protocol method to the [0.6.1] — Added section in both EN and IT changelogs. EN: 'Directory Index Integrity' IT: 'Integrità dell'\''Indice di Directory'
- mkdocs-basic: add intentional FILE_NOT_FOUND + BROKEN_ANCHOR (fail_under=0) - run_demo.sh: expand from 5 to 9 acts (Acts 0-8); fix header 'Seven' to 'Nine acts' - examples/zensical-bridge: Transparent Proxy demo (engine=zensical, mkdocs.yml only) - examples/docusaurus-v3-enterprise: versioned docs, @site/ aliases, i18n Ghost Routing - examples/vanilla-markdown: MISSING_DIRECTORY_INDEX on bare .md tree All examples pass `zenzic check all` with expected exit codes.
…rocess
- src/zenzic/lab.py: new CLI command — 9 acts, all bundled examples, pure Python
- src/zenzic/main.py: wire `lab` into the app under rich_help_panel='Core'
- pyproject.toml: add force-include to bundle examples/ into the PyPI wheel
Path resolution: importlib.resources.files('zenzic') for installed wheels,
fallback to repo root for editable installs. Both verified in clean-env test.
Design decisions:
- Zero subprocess: all checks run via internal _collect_all_results() API
- _apply_target() reused for single-file and custom-dir acts (Acts 4 and 5)
- model_copy(update=) for config patches — no mutation of loaded config
- Summary table at end; no typer.Exit() per-act (lab is a demo, not a CI gate)
- README.md + README.it.md: strip --pre from all install snippets and CI/CD examples
- Remove include_prereleases from PyPI badge URL
- Replace verbose venv install block with clean 3-command flow:
pip install zenzic / zenzic lab / zenzic check all
- examples/docusaurus-v3 install.mdx (EN+IT): uvx --pre -> uvx
v0.6.1 'Obsidian Glass' is stable. No pre-release flag needed.
Streamline copilot-instructions.md to reflect current CLI shape: - Remove stale references to pre-release --pre flag - Align build/test commands with current justfile/noxfile - Reflect zenzic lab, Vanilla mode, and v0.6.1 feature set
Apply CEO directives 027 and 029 to both README files: Direttiva 027 — Precision over Magic: - Replace 'auto-detects'/'rileva automaticamente' with deterministic language throughout (Try it now section + FAQ + narrative text) - EN: 'Zenzic identifies the engine from config files present' - IT: 'Zenzic identifica il motore dai file di configurazione presenti' Direttiva 029 — Link Parity & Truth Audit: - Fix README.it.md line 69: [Badge][docs-it-home] -> [docs-it-badges] - Add missing [docs-it-badges] definition: /it/docs/usage/badges/ - Fix [docs-it-home] target: /it/docs/usage/ -> /it/docs/ (mirrors EN) - All 4 docs-it-* refs now have exact bilingual parity with EN counterparts Structural (both files): - Lean 19-section mirror structure (EN 396 lines / IT 398 lines) - Remove 350+ lines of redundant prose from previous version - Fix DEAD_DEF warnings: add engine hyperlinks to Multi-Engine tables zenzic check all --strict: All checks passed
…iva 036-040) BREAKING CHANGE: engine = "vanilla" now raises ConfigurationError [Z000]. Update zenzic.toml to engine = "standalone" before upgrading. - Rename VanillaAdapter -> StandaloneAdapter (_vanilla.py -> _standalone.py) - Add migration guard in _factory.py: engine="vanilla" raises Z000 (sunset v0.7.0) - Add src/zenzic/core/codes.py: Zxxx finding code registry (single source of truth) - Normalize all Finding codes to Zxxx via _normalize_code() in cli.py - scanner.py: _map_shield_to_finding emits Z201 instead of SHIELD - lab.py: no-arg invocation shows act menu; positional arg runs single act - Act 8 renamed to "Standalone Excellence" - pyproject.toml entry-point: vanilla -> standalone - examples/vanilla-markdown -> examples/standalone-markdown - zenzic.toml: engine = "standalone" (dogfood self-check) - .github/copilot-instructions.md: restored institutional memory (Direttiva 040) - CHANGELOG.md, CHANGELOG.it.md: Breaking Changes + Added sections under [0.6.1] - RELEASE.md: new headline, Standalone + Zxxx sections, migration note - All test files migrated: test_vanilla_mode.py -> test_standalone_mode.py - Test suite: 1127 passed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Final stable release of the v0.6.1 series.
This PR consolidates the "Obsidian Glass" vision, realigning the core with
official engine specifications and introducing the Obsidian Seal of integrity.
Key Highlights:
Verified with 1,130 tests. Zero-trust, subprocess-free.