zenzic 0.28.0

Deterministic Document Integrity Engine for Markdown/MDX graphs.
Tiered code governance, frozen security contracts, and RE2-backed deterministic scanning.

Treat your Markdown documentation like production code.

Zenzic detects broken links, orphaned pages, credential leaks, and structural integrity issues before they reach production.

⚡ Unified Ecosystem Platform

Zenzic is a unified, deterministic platform structured into three primary delivery mechanisms:

• Core Engine (CLI): Python CLI, AST rule engine, Virtual Site Map (VSM) topology analyzer, and Baseline & Regression Tracking (.zenzic-baseline.json).
• VS Code Extension: Real-time LSP client offering sub-50ms inline diagnostics, Quick Fixes, and DQS scoring.
• GitHub Action: Zero-config CI/CD quality gate with SARIF upload and PR annotations.

🚀 Deterministic 3-Step Quickstart (< 60 Seconds)

Experience zero-config topological failure detection in under 60 seconds:

# Step 1: Install Zenzic CLI
uv tool install zenzic

# Step 2: Initialize workspace and create a broken link
zenzic init
mkdir -p docs
echo "[broken](missing.md)" > docs/index.md

# Step 3: Run full documentation graph analysis
zenzic check all

Expected Output:

docs/index.md:1  [Z104]  'missing.md' resolves to nowhere — the target file does not exist.

FAILED: Hard errors detected. Exit code 1 is mandatory.

Next Steps: Real-Time Feedback

To eliminate the latency between authoring a defect and discovering it, install the Zenzic VS Code Extension for real-time inline diagnostics and automated Quick Fixes.

🛡️ 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 LLM sampling, and no network-dependent results injected into the analysis path.

Documentation Security

Zenzic treats documentation as a security surface. 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.
• Suppression CAP: A configurable ceiling on the total number of active zenzic:ignore suppressions. Exceeding it blocks the build.

Zero Hallucinations

Zenzic reports only what is statically verifiable in the repository at scan time. It never infers intent or approximates link validity. Every finding is a falsifiable, reproducible fact.

Topological Graph Analysis (Orphans & Dead Ends)

Beyond static file checks, Zenzic's Smart Link Graph builds an adjacency list to perform Breadth-First Search (BFS) over your document network. It identifies Topological Orphans (Z410, documents unreachable from navigation entry points) and Dead Ends (Z411, pages with no outgoing links), helping maintain structural navigation integrity.

🧠 Key Capabilities & Commands

Headless Data Pipeline (SARIF Output)

Zenzic Core is headless and emits standardized SARIF JSON, ensuring seamless integration with modern CI dashboards:

{
  "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
  "version": "2.1.0",
  "runs": [
    {
      "tool": {
        "driver": {
          "name": "zenzic",
          "version": "0.28.0",
          "rules": [
            {
              "id": "Z101",
              "name": "BrokenLink"
            }
          ]
        }
      }
    }
  ]
}

🔌 Multi-Engine Support

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

🔄 CI/CD & Responsibility Matrix (ADR-075)

Zenzic Core is radically unaware of any CI platform. Platform-specific behaviour — GitHub Annotations, Code Scanning upload, PR decoration — is the sole responsibility of the Zenzic Action.

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

📦 Installation & Upgrading

# Global CLI tool (Recommended)
uv tool install zenzic

# Pinned dev dependency
uv add --dev zenzic

# pip
pip install zenzic

If you installed Zenzic globally via uv, you must explicitly request an upgrade to fetch the latest deterministic engine:

uv tool upgrade zenzic

To run a specific version ephemerally without altering your global environment:

uvx zenzic@0.28.0 check all

📖 Documentation & Support

🤝 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