Evidence Pipeline & Linting

Starting with v2.0, ZiraDocs includes a strict linter and an Evidence Pipeline designed to integrate with CI/CD, DevSecOps tools, and third-party validation systems.

Diagnostic Reports

The toolchain can output machine-readable diagnostic reports detailing the results of the parsing and linting phases. You can generate these reports by passing the --report flag to slidelang build or doclang build.

Supported Formats

• JSON (--report json): A compact, easy-to-parse proprietary JSON structure. It includes an array of diagnostics, plus a document object with a SHA-256 checksum and the schemaVersion.
• SARIF (--report sarif): Standardized SARIF 2.1.0 format, widely used by static analysis tools and natively supported by GitHub Advanced Security.

By default, the report is printed to standard output (stdout), making it easy to pipe to other tools or uploaders. You can also direct it to a file using --report-out filename.json.

slidelang build slides.slidelang --report sarif > evidence.sarif

Waivers (Policy Overrides)

In real-world usage, some warnings may be intentional (e.g. using a deprecated but necessary element, or temporarily bypassing a best-practice rule). ZiraDocs allows you to specify waivers via a lint_policy configuration.

Waivers can be defined inside the document’s frontmatter or in an external YAML/JSON configuration file (passed via --lint-config).

Frontmatter Example

---
title: "My Presentation"
lint_policy:
  - id: "warn-deprecated-element"
    justification: "We need this specific layout for Q3."
    expires_at: "2026-12-31T23:59:59Z"
---

When a rule is waived, it will still appear in the report but will be marked explicitly as waived or suppressed (e.g., using SARIF’s suppressions array).

External Rulepacks

For organizations with proprietary guidelines, or developers who want to write custom rules in languages other than Go, ZiraDocs supports External Rulepacks.

An external rulepack is any executable that can accept the ZiraDocs AST via standard input and return an array of findings via standard output.

slidelang build slides.slidelang --rulepack ./my-custom-linter

The Protocol

When a rulepack is invoked, the ZiraDocs CLI pipes the entire parsed AST to the rulepack’s stdin. The rulepack evaluates the AST and must output a JSON object containing a manifest and findings:

{
  "reportVersion": "1.0",
  "manifest": {
    "name": "AcmeCorp Linter",
    "version": "1.2.0",
    "prefix": "ACME"
  },
  "findings": [
    {
      "id": "ACME001",
      "severity": "error",
      "message": "Brand guidelines forbid this color.",
      "startLine": 12,
      "startColumn": 5
    }
  ]
}

The toolchain automatically merges these findings into the final report, tagging them with the correct provenance (e.g., AcmeCorp Linter@1.2.0) and matching them against active waivers.