Contract Reference

This page is now a short summary of the CLI-consumed plugin contract. The implementation-coupled source of truth belongs in the Divekit CLI repository.

Stable Summary

The CLI currently expects the following:

• plugin discovery requires plugin.json and either ci.yaml or ci.yml; ci.yaml is preferred when both exist
• optional materialized plugin assets live in feedback/; plugin code under src/ ships in the plugin image and is ignored by CLI materialization
• stable SemVer refs such as v1.2.3 are materialized from GitLab release ZIP assets when available; branch and commit refs are read from the repository tree
• plugin state is stored in:
  • .divekit/eval-pipeline/plugins.json
  • .divekit/distributions/<distribution>/eval-pipeline/plugins.json
  • ~/.divekit/plugin-sources.json
• managed plugin files are stored in:
  • .divekit/eval-pipeline/eval/.gitlab/ci/divekit/plugins/<plugin-id>.yml
  • .divekit/eval-pipeline/eval/.gitlab/ci/divekit/plugins/<plugin-id>/feedback/**
  • .divekit/distributions/<distribution>/eval-pipeline/eval/.gitlab/ci/divekit/plugins/<plugin-id>.yml
  • .divekit/distributions/<distribution>/eval-pipeline/eval/.gitlab/ci/divekit/plugins/<plugin-id>/feedback/**
• plugin jobs receive DIVEKIT_PLUGIN_DIR, pointing to the materialized .gitlab/ci/divekit/plugins/<plugin-id> directory for optional assets such as feedback
• normalized reporting uses:
  • plugin-results/<plugin-id>/report.json
• optional run-specific feedback uses:
  • plugin-results/<plugin-id>/feedback.md
  • plugin-results/<plugin-id>/feedback/index.json
  • plugin-results/<plugin-id>/feedback/**/*.md
• optional execution issues use:
  • plugin-results/<plugin-id>/issues/index.json
  • plugin-results/<plugin-id>/issues/**/*.md
  • plugin-results/<plugin-id>/logs/**
• manual report overrides are read from:
  • .divekit/overrides/*.json
  • .divekit/plugin/overrides/*.json (legacy)
• generated GitLab Pages expose feedback and issues in index.html, feedback.json, and issues.json
• plugin refs are selected explicitly and are typically Git tags such as vX.Y.Z; release ZIP assets should contain ci.yaml or ci.yml at the archive root and may include feedback/**; legacy src/** entries are accepted and ignored
• plugin.json.version is not the authoritative version source
• named discovery sources such as official are resolved through plugin-sources.json, not stored as raw repository URLs

Report entries can include optional notices for short, display-only annotations above that entry’s report body:

[
  {
    "id": "test-3",
    "name": "Test 3",
    "category": "Tests",
    "status": "success",
    "notices": [
      {
        "tone": "warning",
        "title": "Accepted by plugin policy",
        "message": "2 of 8 tests passed. This result is accepted by the plugin grading rule."
      }
    ],
    "content": "<p>Details for the test.</p>"
  }
]

title and message are plain text. They do not support Markdown or HTML. Supported tones are info, warning, success, and danger.

For feedback items with type: "faq", use title as the question. The referenced Markdown content should start with the same question as a # heading and then answer it.

Feedback items can optionally set defaultOpen to control the initial expanded/collapsed state on the generated Page. If defaultOpen is omitted, test-specific feedback is expanded by default and global feedback is collapsed by default.

Use issues for execution problems that are not test results, such as build failures, plugin failures, or missing tool output. issues/index.json items can reference Markdown explanations and optional log files. If affectsResult is true, the generated Page treats the evaluation as incomplete/failed without creating a fake test.

Manual report overrides can force the status of selected plugin results after reports are collected. Override files live directly below .divekit/overrides/ in eval repositories. Older repositories may still use the legacy .divekit/plugin/overrides/ location; Divekit keeps reading it for compatibility. Override files have this shape:

{
  "version": "1.0",
  "id": "jacoco-pit-coverage-threshold-20260529T091500Z",
  "reason": "Accepted after manual review",
  "createdAt": "2026-05-29T09:15:00Z",
  "targets": [
    {
      "plugin": "jacoco-pit",
      "testId": "coverage-threshold",
      "status": "success"
    }
  ]
}

Each target selects one plugin and either testId, category, category plus name, or all: true. Supported statuses are success, warning, failure, and fatal. If multiple overrides match the same report result, the last matching override wins after sorting override files by path.

Source of Truth

Use the Divekit CLI repository for the current semantic contract:

• docs/reference/plugin-contract.md

That document should remain authoritative for:

• discovery semantics
• CLI-managed state files
• normalized report consumption
• managed plugin identifiers and source behavior