Skip to content

findings-schema.md

Latest commit

 

History

History
132 lines (103 loc) · 4.26 KB

findings-schema.md

File metadata and controls

132 lines (103 loc) · 4.26 KB
Raw

Findings Schema

The canonical review artifact is .artifacts/diffpal/findings.json, a JSON serialization of DiffPal's findings bundle. New review writes use version: "v3" unless a bundle version is already set by the caller.

Canonical Bundle

Field Required Meaning
version yes Bundle version. New writes use v3; readers accept v1, v2, and v3.
review_id yes Stable review identifier.
base_sha yes Base revision used for the review.
head_sha yes Head revision used for the review.
language no Language requested for generated text.
prompt no Prompt metadata.
inspection no Provider inspection metadata.
change_summary no Human-readable summary bullets.
review_result no Human-readable review outcome sentence.
files no Reviewed files.
findings yes Finding array. May be empty.

Prompt metadata fields:

Field Meaning
prompt_id Prompt identifier, currently diffpal.review for review output.
prompt_version Prompt version used for the review.
purpose Prompt purpose.
schema_version Prompt output schema version, currently findings.v3.

Inspection metadata fields:

Field Meaning
provider_type Runtime provider type when available.
required Whether inspection metadata was required by the runtime.
tool_calls Tool call names when available.
diff_inspected Whether the provider reported diff inspection.
context_inspected Whether the provider reported context inspection.

Finding Fields

Field Required Meaning
id written by DiffPal Deterministic fingerprint.
review_id written by DiffPal when missing Review identifier copied from the bundle.
category yes Finding category.
severity yes low, medium, high, or critical.
confidence yes Number from 0 to 1.
path yes File path for the finding.
start_line yes Positive start line.
end_line yes Positive end line, greater than or equal to start_line.
changed_span yes for v2/v3 Changed-line span that anchors the finding.
supporting_span no Additional context span.
title yes Short finding title.
message yes Finding explanation.
evidence yes Structured evidence for v2/v3.
impact yes Structured impact for v2/v3.
suggestion no Suggested fix.
blocking written by DiffPal Whether the finding meets the active threshold.
provider no Provider ID that produced the finding.

Line span representation:

{
  "path": "internal/session.go",
  "start_line": 12,
  "end_line": 14
}

Evidence representation:

{
  "anchor": "changed lines call exec with request input",
  "reasoning_basis": "the command arguments now include unsanitized user data",
  "source": "changed_line"
}

Impact representation:

{
  "summary": "users can execute unintended shell commands",
  "scope": "request handling path"
}

Severity And Location

Allowed severities are low, medium, high, and critical. DiffPal normalizes severity to lowercase.

Location is represented twice for compatibility:

  • path, start_line, and end_line are the primary line fields;
  • changed_span carries the same changed-line anchor in structured form.

For v2/v3, changed_span.path, changed_span.start_line, and changed_span.end_line are required and must be positive.

Compatibility

DiffPal readers accept:

  • v1 bundles where evidence and impact may be legacy strings;
  • v2 bundles with structured evidence and impact;
  • v3 bundles with optional review_result.

New writes use v3. Consumers should ignore unknown fields and treat findings[] as the canonical machine-readable issue list.

Consumer Example

Fail a CI step when the canonical bundle contains blocking findings:

jq -e '[.findings[] | select(.blocking == true)] | length == 0' \
  .artifacts/diffpal/findings.json

Count high and critical findings regardless of whether the gate was enabled:

jq '[.findings[] | select(.severity == "high" or .severity == "critical")] | length' \
  .artifacts/diffpal/findings.json