zenzic 0.6.1

Engineering-grade, engine-agnostic linter and security shield for Markdown documentation

🛡️ Zenzic

Zenzic Shield internally audits this repository for credential leaks on every commit.

The Safe Harbor for your Markdown documentation.
Engine-agnostic static analysis — standalone, security-hardened, zero configuration needed.

---

⚡ Try it now — Zero Installation

Got a folder of Markdown files? Run an instant security and link audit using uv:

uvx zenzic check all ./your-folder

Zenzic will identify your engine via its configuration files or default to Vanilla mode for standalone folders — providing immediate protection for links, credentials, and structural integrity.

---

🚀 Quick Start

pip install zenzic
zenzic lab        # Interactive showroom — 9 acts, every engine, zero setup
zenzic check all  # Audit the current directory

📖 Full docs → · 🏅 Badges · 🔄 CI/CD guide

---

🎯 Why Zenzic?

Without Zenzic	With Zenzic
❌ Broken anchors silently 200 OK in Docusaurus v3	✅ Mathematical anchor validation via VSM
❌ Leaked API keys in code blocks committed to git	✅ The Shield — 9-family credential scanner, exit 2
❌ Path traversal ../../../../etc/passwd in links	✅ Blood Sentinel — non-suppressible exit 3
❌ Orphan pages unreachable from any nav link	✅ Semantic orphan detection — not just file-exists
❌ Silent 404s accumulating in Google Search Console	✅ Directory Index Integrity checks
❌ MkDocs → Zensical migration with unknown breakage	✅ Transparent Proxy — lint both with one command

---

🧩 What Zenzic is NOT

• Not a site generator. It audits source; it never builds HTML.
• Not a build wrapper. Zero-Trust Execution: no subprocesses, no mkdocs or docusaurus binaries invoked.
• Not a spell checker. Structure and security — not prose.
• Not an HTTP crawler. All validation is local and file-based.

---

📋 Capability Matrix

Capability	Command	Detects	Exit
Link integrity	check links	Broken links, dead anchors	1
Orphan detection	check orphans	Files absent from nav — invisible after build	1
Code snippets	check snippets	Syntax errors in Python / YAML / JSON / TOML blocks	1
Placeholder content	check placeholders	Stub pages and forbidden text patterns	1
Unused assets	check assets	Images and files not referenced anywhere	1
Credential scanning	check references	9 credential families — text, URLs, code blocks	2
Path traversal	check links	System-path escape attempts	3
Quality score	score	Deterministic 0–100 composite metric	—
Regression detection	diff	Score drop vs saved baseline — CI-friendly	1

Autofix: zenzic clean assets [-y] [--dry-run] deletes unused images.

🚀 v0.6.1 "Obsidian Glass" (Stable) — Full Docusaurus v3 versioning, @site/ alias resolution, and Zensical Transparent Proxy. See CHANGELOG.md.

---

🛡️ Security: The Shield & Blood Sentinel

Two security layers are permanently active — neither is suppressible by --exit-zero:

The Shield scans every line — including fenced code blocks — for credentials. Unicode normalization defeats obfuscation (HTML entities, comment interleaving, cross-line lookback). Detected families: AWS, GitHub/GitLab, Stripe, Slack, OpenAI, Google, PEM headers, hex payloads. → Exit 2. Rotate and audit immediately.

Blood Sentinel normalizes every resolved link with os.path.normpath and rejects any path escaping the docs/ root. Catches ../../../../etc/passwd-style traversal before any OS syscall. → Exit 3.

Exit	Meaning
0	All checks passed
1	Quality issues found
2	SECURITY — leaked credential detected
3	SECURITY — system-path traversal detected

Add zenzic check references to your pre-commit hooks to catch leaks before git history.

---

🔌 Multi-Engine Support

Zenzic reads config files as plain text — never imports or executes your build framework:

Engine	Adapter	Highlights
Docusaurus v3	DocusaurusAdapter	Versioned docs, @site/ alias, Ghost Route detection
MkDocs	MkDocsAdapter	i18n suffix + folder modes, fallback_to_default
Zensical	ZensicalAdapter	Transparent Proxy bridges mkdocs.yml if zensical.toml absent
Any folder	VanillaAdapter	Zero-config, Directory Index Integrity — no engine required

Third-party adapters install via the zenzic.adapters entry-point group. See the Developer Guide for the adapter API.

---

⚙️ Configuration

Zero-config by default. Priority: zenzic.toml > [tool.zenzic] in pyproject.toml > built-ins.

# zenzic.toml  (all fields optional)
docs_dir                 = "docs"
fail_under               = 80       # exit 1 if score < threshold; 0 = observe only
excluded_dirs            = ["includes", "assets", "overrides"]
excluded_build_artifacts = ["pdf/*.pdf", "dist/*.zip"]
placeholder_patterns     = ["coming soon", "todo", "stub"]

[build_context]
engine         = "mkdocs"   # mkdocs | docusaurus | zensical | vanilla
default_locale = "en"
locales        = ["it"]

zenzic init             # Generate zenzic.toml with auto-detected values
zenzic init --pyproject # Embed [tool.zenzic] in pyproject.toml

Custom lint rules — declare project-specific patterns in zenzic.toml, no Python required:

[[custom_rules]]
id       = "ZZ-NODRAFT"
pattern  = "(?i)\\bDRAFT\\b"
message  = "Remove DRAFT marker before publishing."
severity = "warning"

Rules fire identically across all adapters. No changes required after engine migration.

---

🔄 CI/CD Integration

- name: 🛡️ Zenzic Sentinel
  run: uvx zenzic check all --strict
  # Exit 1 = quality · Exit 2 = leaked credential · Exit 3 = path traversal
  # Exits 2 and 3 are never suppressible.

- name: Regression gate
  run: |
    uvx zenzic score --save    # on main branch
    uvx zenzic diff            # on PR — exit 1 if score drops

For badge automation and regression gates, see the CI/CD guide. Full workflow: .github/workflows/ci.yml

---

📦 Installation

# Zero-install, one-shot audit (recommended for CI and exploration)
uvx zenzic check all ./docs

# Global CLI tool
uv tool install zenzic

# Pinned dev dependency
uv add --dev zenzic

# pip
pip install zenzic
pip install "zenzic[mkdocs]"   # + MkDocs build-time plugin

The [mkdocs] extra adds the build-time plugin (zenzic.integrations.mkdocs). All engine adapters (Docusaurus, Zensical, Vanilla) are included in the base install.

Portability: Zenzic rejects absolute internal links (starting with /). Relative links work at any hosting path. External https:// URLs are never affected.

---

🖥️ CLI Reference

# Checks
zenzic check links [--strict]
zenzic check orphans
zenzic check snippets
zenzic check placeholders
zenzic check assets
zenzic check references [--strict] [--links]
zenzic check all [--strict] [--exit-zero] [--format json] [--engine ENGINE]
zenzic check all [--exclude-dir DIR] [--include-dir DIR]

# Score & diff
zenzic score [--save] [--fail-under N]
zenzic diff  [--threshold N]

# Autofix
zenzic clean assets [-y] [--dry-run]

# Init
zenzic init [--pyproject]

# Interactive showroom
zenzic lab [--act N] [--list]

---

📟 Visual Tour

╭───────────────────────  🛡  ZENZIC SENTINEL  v0.6.1  ────────────────────────╮
│                                                                              │
│  docusaurus • 38 files (18 docs, 20 assets) • 0.9s                           │
│                                                                              │
│  ────────────────────── docs/guides/setup.mdx ───────────────────────────  │
│                                                                              │
│    ✗ 12:   [Z001]  'quickstart.mdx' not found in docs                        │
│        │                                                                     │
│    12  │ Read the [quickstart guide](quickstart.mdx) first.                  │
│        │                                                                     │
│  ──────────────────────────────────────────────────────────────────────────  │
│                                                                              │
│  ✗ 1 error  • 1 file with findings • FAILED                                  │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯

Visit the documentation portal for interactive screenshots and rich examples.

---

🗺️ Roadmap v0.7.0

• Auto-fix Engine — Automatic repair of broken links and orphaned anchors.
• IDE Extensions — Real-time linting for VS Code and Cursor via LSP.
• AI Context Provider — VSM export in LLM-friendly format for AI agents.
• Astro & VitePress Adapters — Expanding the Safe Harbor to JS frameworks.

---

🏗️ Design Philosophy

Zenzic is built on three operational contracts:

Lint the Source, Not the Build. The VSM (Virtual Site Map) maps every .md file to its canonical URL without running the build — errors are caught before they reach production.

Zero-Trust Execution. No subprocesses, no arbitrary code execution, no build engine imports. Docusaurus .ts/.js configs are parsed via static text analysis — Node.js is never invoked.

Mandatory Exclusion at Every Entry Point. All file discovery goes through LayeredExclusionManager — a 4-level hierarchy (System → VCS → Config → CLI). No global scan without an explicit exclusion context.

See the Architecture Guide for the Two-Pass Reference Pipeline and VSM deep-dive.

---

🙋 FAQ

Why not grep? Grep is blind to structure. Zenzic understands Docusaurus versioning, MkDocs i18n fallbacks, and Ghost Routes — pages that don't exist as files but are valid URLs.

Does it run my build engine? No. 100% subprocess-free. Static analysis on plain text only.

Can it handle thousands of files? Yes. Adaptive parallelism for discovery; O(1) VSM lookup per link; content-addressable cache (SHA256(content + config + vsm_snapshot)) skips unchanged files.

Shield vs Blood Sentinel? Shield = secrets inside content (exit 2). Blood Sentinel = links pointing to OS system paths (exit 3). Both are non-suppressible.

No zenzic.toml needed? Correct. Zenzic identifies the engine from config files present and applies safe defaults. Run zenzic init at any time to generate a pre-populated config file.

What is zenzic lab? A 9-act interactive showroom covering every engine and error class. Run it once before integrating Zenzic into any project.

---

🛠️ Development

uv sync --all-groups
nox -s tests       # pytest + coverage
nox -s lint        # ruff
nox -s typecheck   # mypy --strict
nox -s preflight   # lint + format + typecheck + pytest + reuse
just verify        # preflight + zenzic check all --strict (self-dogfood)

See the Contributing Guide for the Zenzic Way checklist and PR conventions.

---

🤝 Contributing

1. Open an issue to discuss the change.
2. Read the Contributing Guide — Zenzic Way checklist, pure functions, no subprocesses, source-first.
3. Every PR must pass nox -s preflight and include REUSE/SPDX headers on new files.

See also: Code of Conduct · Security Policy

📎 Citing

A CITATION.cff is present at the root. Click "Cite this repository" on GitHub for APA or BibTeX output.

📄 License

Apache-2.0 — see LICENSE.

---

© 2026 PythonWoods. Engineered with precision.
Based in Italy 🇮🇹  ·  Committed to the craft of Python development.
[e-mail]