Deterministic audit of documentation structures with bidirectional traceability.
Tiered code governance, frozen security contracts, and RE2-backed deterministic scanning.

---

⚡ 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 identifies your engine via its configuration files or defaults to Standalone Mode for plain Markdown folders — providing immediate protection for links, credentials, and file integrity.

---

🚀 Quick Start

pip install zenzic
cd my-docs-repo
zenzic init       # Establish the workspace boundary (creates .zenzic.toml)
zenzic check all  # Audit the current directory

🧠 Core Pillars

• Pure, deterministic engine: identical inputs produce identical findings and exits.
• Tiered code model: Core, Structure, and Governance findings grouped by tier.
• Frozen contracts for integrators: FROZEN_CODES, NON_SUPPRESSIBLE_CODES, and PLUGIN_FORBIDDEN_EXITS provide stable enforcement surfaces for CI and plugins.
• Inspect-first workflow: use zenzic inspect codes to validate live code semantics before touching docs or release notes.

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

---

⚙️ Commands Overview

Command	Purpose
zenzic init	Scaffold workspace configuration (.zenzic.toml)
zenzic check all [PATH]	Full documentation audit — links, credentials, orphans
zenzic score [--fail-under N] [--stamp]	Compute the Documentation Quality Score (0–100)
zenzic diff [--base PATH]	Detect debt regression against a saved baseline
zenzic guard scan [PATH]	Defense-in-Depth credential pre-gate (fatal on security findings: exit 2)
zenzic inspect codes	Query live error-code semantics and suppressibility

---

🚀 CI/CD Ready: Use the Official Zenzic Action to run Zenzic in GitHub Actions — findings surface directly in Code Scanning, PR annotations, and the Security tab.

- uses: PythonWoods/zenzic-action@v2
  with:
    format: sarif
    upload-sarif: "true"

📊 Headless Data Pipeline (SARIF Output)

Zenzic Core is headless and emits standardized SARIF (Static Analysis Results Interchange Format) JSON, ensuring seamless integration with modern CI dashboards and scanning services:

{
  "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
  "version": "2.1.0",
  "runs": [
    {
      "tool": {
        "driver": {
          "name": "zenzic",
          "version": "0.16.0",
          "rules": [
            {
              "id": "Z101",
              "name": "BrokenLink",
              "shortDescription": { "text": "Broken documentation link" }
            }
          ]
        }
      },
      "results": [
        {
          "ruleId": "Z101",
          "level": "error",
          "message": { "text": "Broken documentation link — ./setup.md#prerequisites" },
          "locations": [
            {
              "physicalLocation": {
                "artifactLocation": { "uri": "docs/getting-started.md" },
                "region": { "startLine": 23 }
              }
            }
          ]
        }
      ]
    }
  ]
}

---

🔌 Multi-Engine Support

Engine	Adapter	Highlights
MkDocs	MkDocsAdapter	i18n suffix + folder modes, fallback_to_default
Zensical	ZensicalAdapter	Transparent Proxy bridges mkdocs.yml
Any folder	StandaloneAdapter	File integrity checks — orphan detection disabled without a nav contract

See the Adapter API for the plugin interface. Third-party adapters install via the zenzic.adapters entry-point group.

---

⚙️ Configuration

Zero-config by default. See the Configuration Guide for the full .zenzic.toml schema and pyproject.toml embedding.

zenzic init        # Generate .zenzic.toml with auto-detected values

---

🔄 CI/CD Integration

- uses: PythonWoods/zenzic-action@v2
  with:
    format: sarif
    upload-sarif: "true"

For zero-install uvx integration and regression gates, see the CI/CD guide.

---

🧩 Ecosystem & CI Integration

Responsibility Matrix: Core vs Action

Zenzic Core is radically unaware of any CI platform. It produces portable, self-contained artefacts (SARIF, JSON, text) via a stable exit-code contract. Platform-specific behaviour — GitHub Annotations, Code Scanning upload, PR decoration — is the sole responsibility of the Zenzic Action.

Concern	Zenzic Core	Zenzic Action
Link validation (Z1xx)	✅	—
Credential scanner (Z2xx)	✅	—
Topology / orphan detection (Z3xx–Z6xx)	✅	—
SARIF / JSON / text output	✅	—
Exit-code contract (0 / 1 / 2 / 3)	✅	enforced
GitHub Annotations (::error::)	—	✅
Code Scanning SARIF upload	—	✅
PR inline diff annotations	—	✅
DQS regression blocking (zenzic diff)	—	✅
Sovereign nightly audit (--audit)	—	✅
GitLab / Bitbucket / other CI adapters	—	future adapters

Design law (ADR-075): logic that maps Zenzic output to a CI platform's native format must live in the Adapter, never in the Core. Exit codes 2 and 3 propagate unchanged through every adapter — they are never remapped or suppressed.

---

🛡️ Why Zenzic?

Determinism

Every Zenzic run is a pure function of its inputs. Given the same repository state and .zenzic.toml, the output — finding codes, severity levels, exit code, SARIF structure — is bit-for-bit identical across machines, platforms, and time. There are no probabilistic judgements, no sampling, and no network-dependent results injected into the analysis path.

Property	Guarantee
Same inputs → same output	✅ Always
RE2-backed regex engine	✅ No backtracking, no catastrophic matching
Frozen finding codes	✅ FROZEN_CODES set; never renamed or silently retired
Reproducible CI artefacts	✅ Identical SARIF across runner OS and time

Documentation Security

Zenzic treats documentation as a security surface, not just a quality metric. The tiered code model enforces a hard boundary between quality findings (suppressible, exit 1) and security findings (non-suppressible, exit 2 / 3):

• Z201 — Credential Scanner: hardcoded tokens, API keys, and secret patterns detected before they reach a PR.
• Z202 / Z203 — Path Traversal Guard: filesystem boundary violations caught at the scan boundary — fail-on-error: false has zero effect.
• Suppression CAP: a configurable ceiling on the total number of active zenzic:ignore suppressions. Exceeding it blocks the build, preventing systematic suppression debt from accumulating silently.

Zero Hallucinations

Zenzic reports only what is statically verifiable in the repository at scan time. It never:

• infers intent or "probable" correctness from surrounding context,
• approximates link validity without a deterministic check,
• emits a finding it cannot reproduce on a re-run with identical inputs.

This makes every Zenzic finding a falsifiable, reproducible fact — suitable as audit evidence, not just developer feedback.

---

📦 Installation

🏗️ Monorepo Architecture: Zenzic contains its own documentation portal. To develop locally, install the documentation toolchain with uv sync --extra docs.

# 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

---

📖 Documentation

Area	URL	Audience
👤 User Guide	zenzic.dev	Install, configure, CI/CD, finding codes
🔧 Developer Portal	zenzic.dev/developers	Adapters, ADRs, CLI architecture, mutation testing
🛡️ Security	Engineering Ledger · SECURITY.md	Security reviewer

---

🤝 Contributing

1. Open an issue to discuss the change.
2. Read the Contributing Guide.
3. Every PR must pass just verify and include 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.

This project strictly adheres to Semantic Versioning.

---

Engineered with precision by PythonWoods in Italy 🇮🇹
"Building the Standard for Technical Document Integrity."

Documentation · GitHub · Blog