spp findings

spp findings merge <file...> [--json] [--verdict <round> ...] [--fix-diff <file>] merges the review panel's Persona findings. Each file is one PersonaFindings. Findings under 80 confidence are dropped. The rest merge in two passes per file: findings whose titles match once case and punctuation are ignored, less than 5 lines from the first of them, form a title cluster; then title clusters whose first lines are less than 5 lines from the first line of the group they join fold into one finding whatever their titles, so a defect that several Personas word differently counts once. A title cluster is never split. The merged finding keeps the highest severity and every Persona, and its body ends with one Also reported as: <title> (<Persona>, line <line>) line for each other title. Its Law tag is the speaking finding's when that cites one. A tagged title (ticket-mandated:, Candidate ADR:, Check after deploy: or Terminology) merges only with its own tag. --verdict adds the panel's verdict over the merged list, as a last Verdict: line or, with --json, a verdict key; from round 3 a FIX FIRST is written HUMAN DECISION. With --json it prints PanelFindings. --fix-diff names the patch of the fixes the round reviewed: each merged finding with any of its findings on a line that patch added or changed, and not merged with a recheck- file's finding, records a fix-regression Signal (the Signal gates apply), and a line on stderr says whether it was recorded. Each merge with --fix-diff also records one run of implement-issue step fix round, which is what the fix-regression rate is counted over. The run is named by the patch's content, fix diff <hash> (the first 12 hex characters of its SHA-256), after pull request <N> when the patch sits in the panel's spp-panel-<N> folder, so merging the same round again records no second run. stdout, the --json shape and the exit code do not change.

Functions¶

run()¶

function run(args): Promise<number>;

Merges Persona findings files and, with --verdict, gives the panel's verdict.

Parameters¶

Returns¶

Promise\<number>

0 when it printed the merged list; 2 on a usage error, with the usage on stderr; 1 when a file cannot be read (the --fix-diff patch included) or does not hold Persona findings, with the reason on stderr.

Example¶

spp findings merge correctness.json security.json --json
spp findings merge *.json --verdict 1 --spec pass --coherence pass --verify pass --checks pass
spp findings merge "$ROUND_DIR"/*.json --fix-diff "$PANEL_DIR/fix-2.patch"

Variables¶

USAGE¶

const USAGE: string;

The usage text spp findings --help prints.

usage: spp findings merge <file...> [--json] [--fix-diff <file>]
         [--verdict <round> --spec pass|fail --coherence pass|fail --verify pass|fail
          --checks pass|fail|pending|none [--missing name,name]]
Each file is { "persona": NAME, "findings": [{ file, line, title, severity, confidence, law?, body }] }.
Findings under 80 confidence are dropped. On one file, findings whose titles match (case and punctuation ignored)
merge within 5 lines of the first of them; then those title groups merge whatever their titles when a group's first line is within 5 lines of
the first line of the merged group. The result keeps the highest severity and every persona, with an
"Also reported as: <title> (<persona>, line <line>)" line in the body for each other title. A title that starts
ticket-mandated:, Candidate ADR:, Check after deploy: or Terminology merges only with findings that start the same
way. --json prints { findings, counts: { severity, persona } }.
--verdict adds the panel's verdict (MERGE, FIX FIRST or HUMAN DECISION) as a last "Verdict:" line, or a "verdict"
key with --json. <round> is 1 for the first panel; from round 3 a FIX FIRST is written HUMAN DECISION. The other
flags are the readings the verdict also depends on; --missing names Personas that never reported.
--fix-diff <file> is the patch of the fixes made since the previous round. A merged finding with any of its findings
on a line it added or changed, and not merged with a finding from a recheck-* file, records a fix-regression Signal; stderr gets one
"fix-regression <id> recorded" or "fix-regression <id> not recorded: <reason>" line per such finding.

Type Aliases¶

PanelFindings¶

type PanelFindings = object;

The panel's findings after the merge: the --json shape of spp findings merge.

Properties¶

Severity¶

type Severity = "critical" | "important" | "minor";

How much a finding matters.

Finding¶

type Finding = object;

One finding as a Persona reports it.

Properties¶

PersonaFindings¶

type PersonaFindings = object;

One Persona's findings file, the input of spp findings merge.

Properties¶

Merged¶

type Merged = object;

A finding after the merge, standing for every Persona finding it absorbed.

Properties¶

PanelVerdict¶

type PanelVerdict = "MERGE" | "FIX FIRST" | "HUMAN DECISION";

The panel's verdict: FIX FIRST when a reading failed, a Persona never reported or a critical finding that is not ticket-mandated stands (HUMAN DECISION from round 3 on); else HUMAN DECISION when an important finding stands, the checks are pending or a finding is ticket-mandated; else MERGE.