zenzic 0.23.1

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

🚀 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.23.1",
          "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

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

📝 IDE Integration

Zenzic provides a Language Server Protocol (LSP) backend via the zenzic lsp command, bringing real-time structural analysis and error reporting directly into your editor.

Note: The official VS Code extension is currently in Private Beta and will be released to the Microsoft Marketplace soon.

⚙️ 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.

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.

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

Upgrading 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.23.1 check all

📖 Documentation

🤝 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