diff

Documentation

Overview

Package diff compares two Draugr scan results and classifies every finding as new, fixed, or unchanged — the security delta of a change (typically a PR's head vs the base branch). It powers `draugr diff` and its differential gate ("fail only on findings this change introduces").

Inputs are SARIF reports (the results.sarif that `draugr scan -o` writes): SARIF is Draugr's complete, structured result currency, whereas the JSON summary can be trimmed by --min-priority.

Index

• func Formats() []string
• func Render(w io.Writer, format string, r Result) error
• type PriorityCounts
• type Result
  • func Compare(base, head sarif.Report) Result
  • func (r Result) GateNew(failOn sarif.Level, failOnPriority string) []sarif.Result
  • func (r Result) NarrowNew(band string) Result
• type SeverityCounts

Functions

func Formats

func Formats() []string

Formats lists the diff output formats, sorted.

func Render

func Render(w io.Writer, format string, r Result) error

Render writes the diff in the named format. Unknown formats error.

Types

type PriorityCounts

type PriorityCounts struct {
	P1 int `json:"p1"`
	P2 int `json:"p2"`
	P3 int `json:"p3"`
	P4 int `json:"p4"`
}

PriorityCounts tallies findings by action band. Unprioritized findings are not counted here.

type Result

type Result struct {
	New       []sarif.Result // present in head, absent in base
	Fixed     []sarif.Result // present in base, absent in head
	Unchanged []sarif.Result // present in both (head copy)
}

Result is the classified delta between a base and a head report.

func Compare

func Compare(base, head sarif.Report) Result

Compare classifies every finding across the two reports by stable identity.

func (Result) GateNew

func (r Result) GateNew(failOn sarif.Level, failOnPriority string) []sarif.Result

GateNew returns the new findings that meet the differential gate: level at or above failOn (when set) OR priority at or above failOnPriority (when set). An empty threshold disables that dimension. With both empty, nothing is returned.

func (Result) NarrowNew

func (r Result) NarrowNew(band string) Result

NarrowNew drops new findings below a priority band, leaving fixed and unchanged alone.

Only the new ones, because they are what the diff is reporting and what a reviewer is asked to act on; fixed and unchanged are context, and a count of them that moved with a threshold would mean something different on every run.

A finding the scanner never prioritized is kept. An empty Priority means prioritization did not run for it, not that it ranked low — dropping it would hide a finding for the reason it was hardest to judge.

type SeverityCounts

type SeverityCounts struct {
	Critical int `json:"critical"`
	High     int `json:"high"`
	Medium   int `json:"medium"`
	Low      int `json:"low"`
}

SeverityCounts tallies findings by Draugr's normalized severity band.

Bands rather than SARIF levels, because a diff is read next to the scan report it came from and the two have to agree. error/warning/note is the wire vocabulary of the file; a reader deciding whether a pull request made things worse is thinking in critical/high/medium/low.