Contratto API JSON

Questa pagina definisce il contratto JSON stabile consumato da CI/CD e automazioni downstream.

Output coperti:

• zenzic check all --format json
• zenzic score --format json
• zenzic check all --format json quando scatta il fail-hard del CAP soppressioni

Lo schema canonico è zenzic-output.schema.json nella root del repository zenzic.

Campi Soppressione Obbligatori

Tutti gli output sopra includono sempre questi campi:

Campo	Tipo	Significato
suppression_count	intero	Soppressioni attive (inline + per-file)
suppression_cap	intero	CAP governance configurato
suppression_debt_pts	intero	Punti di debito (max(0, suppression_count - suppression_cap))
debt_status	enum	Postura del debito governance

Valori debt_status:

• CLEAN: suppression_count == 0
• MANAGED: 0 < suppression_count <= suppression_cap e suppression_cap <= 30
• EXTENDED: 0 < suppression_count <= suppression_cap e suppression_cap > 30
• CRITICAL: suppression_count > suppression_cap

Shape: JSON check all

{
  "links": [],
  "orphans": [],
  "snippets": [],
  "placeholders": [],
  "unused_assets": [],
  "references": [],
  "nav_contract": [],
  "suppression_count": 0,
  "suppression_cap": 30,
  "suppression_debt_pts": 0,
  "debt_status": "CLEAN"
}

Shape: JSON score

{
  "project": "zenzic",
  "score": 100,
  "threshold": 0,
  "status": "success",
  "timestamp": "2026-05-17T10:00:00+00:00",
  "categories": [
    {
      "name": "structural",
      "weight": 0.3,
      "issues": 0,
      "category_score": 1.0,
      "contribution": 0.3,
      "raw_penalty": 0.0,
      "is_capped": false
    }
  ],
  "suppression_count": 0,
  "suppression_cap": 30,
  "suppression_debt_pts": 0,
  "debt_status": "CLEAN"
}

I campi score opzionali (security_override, security_findings) appaiono quando scatta il Security Override.

Shape: JSON CAP Fail-Hard

{
  "error": "SUPPRESSION_CAP_EXCEEDED",
  "severity": "error",
  "message": "Suppression cap exceeded: 31/30. Architectural debt limit reached.",
  "suppression_count": 31,
  "suppression_cap": 30,
  "suppression_debt_pts": 1,
  "debt_status": "CRITICAL",
  "statistics": {
    "active_suppressions": 31,
    "configured_global_cap": 30,
    "excess_debt": 1,
    "inline_ignores": 31,
    "per_file_ignores": 0
  },
  "hotspots": [
    {
      "path": "docs/index.md",
      "count": 31
    }
  ],
  "remediation": [
    "Review hotspots and remove suppressions where possible."
  ],
  "playbook": "https://zenzic.dev/developers/how-to/release-governance-protocol"
}

Guida Validazione

Per consumer macchina rigorosi, valida i payload con zenzic-output.schema.json in CI. Questo evita drift silenzioso del contratto tra release minori.