R15: pipeline-failed is one finding per failing mover

The finding pipeline-failed has scope delivery and id <module>.<branch>, one per mover whose
required step failed or could not run, naming the pipeline and the steps, owned by the commit's
author as before; that module's next passed pipeline on that branch clears it. Unit tests 84 to
84 (the newer-revision test replaced).

Builds: design 47 H §770; lead answers H-A-19, H-A-59

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
This commit is contained in:
2026-11-20 04:56:31 +01:00
parent 8da18c37c5
commit c9fd571e8e
3 changed files with 73 additions and 109 deletions
@@ -59,9 +59,14 @@ func failedSteps(p seat.Pipeline, module string) []seat.StepResult {
return out
}
func (f *Failures) held(commit string) *condseat.Finding {
// findingID is a mover's finding's id, `<module>.<branch>`, each escaped as a key's name is (design 47 H §770).
func findingID(module, branch string) string { return About(module, branch) }
// held is the finding pipeline-failed of module on branch the findings hold, nil when none (§770).
func (f *Failures) held(module, branch string) *condseat.Finding {
id := findingID(module, branch)
for _, h := range f.Findings.Held() {
if h.Scope == mcc.ScopeMerge && h.ID == commit && h.Kind == PipelineFailedKind {
if h.Scope == mcc.ScopeDelivery && h.ID == id && h.Kind == PipelineFailedKind {
h := h
return &h
}
@@ -69,24 +74,36 @@ func (f *Failures) held(commit string) *condseat.Finding {
return nil
}
// StepEnded is what the end of step s of pipeline p says of its head: a failed required step writes the finding of its commit,
// a step of a commit already found failed that is not one writes its owner when it had none, and a passing required step clears
// the findings of the older revisions it makes good.
// StepEnded raises, for the step s of p just ended, the finding pipeline-failed of its mover when a required step of that
// mover failed or could not run: one finding per failing mover, id `<module>.<branch>` (design 47 H §770, H-A-19, H-A-59).
func (f *Failures) StepEnded(store Updater, p seat.Pipeline, s seat.StepResult) {
m, ok := MoverOf(p, s.Module)
if f == nil || f.Findings == nil || !ok || m.Commit == "" {
if f == nil || f.Findings == nil || !ok {
return
}
ctx := context.Background()
switch {
case len(failedSteps(p, m.Module)) > 0:
f.write(ctx, p, m)
case s.Outcome == seat.StepResultOutcomePassed || s.Outcome == seat.StepResultOutcomeCarried:
f.clearNewer(ctx, store, p, m)
if len(failedSteps(p, m.Module)) > 0 {
f.write(context.Background(), p, m)
}
}
// write raises or rewrites the mover m's finding (§33).
// Ended clears, for a pipeline that ended passed, each of its movers' finding pipeline-failed on its branch: that module's
// next passed pipeline on that branch clears it (§770).
func (f *Failures) Ended(p seat.Pipeline) {
if f == nil || f.Findings == nil || p.Outcome != seat.PipelineOutcomePassed {
return
}
for _, m := range p.Movers {
if f.held(m.Module, p.Branch) == nil {
continue
}
if err := f.Findings.Clear(context.Background(), mcc.ScopeDelivery, findingID(m.Module, p.Branch), PipelineFailedKind,
"the pipeline "+p.Pipeline+" of "+p.Branch+" passed"); err != nil {
f.logf("the finding %s of %s on %s is not cleared: %v", PipelineFailedKind, m.Module, p.Branch, err)
}
}
}
// write raises or rewrites the mover m's finding, naming the pipeline and the steps (§770).
func (f *Failures) write(ctx context.Context, p seat.Pipeline, m seat.Mover) {
steps := failedSteps(p, m.Module)
var names []string
@@ -98,25 +115,26 @@ func (f *Failures) write(ctx context.Context, p seat.Pipeline, m seat.Mover) {
now = f.Now().UTC()
}
owner, why := "", ""
if old := f.held(m.Commit); old != nil {
if old := f.held(m.Module, p.Branch); old != nil {
owner = old.Owner
}
if owner == "" {
owner, why = f.author(m)
}
explanation := fmt.Sprintf("The required steps %s of %s did not pass on the branch %s at the commit %s. A newer commit of the branch that passes them clears this.",
strings.Join(names, ", "), m.Module, p.Branch, m.Commit)
explanation := fmt.Sprintf("The required steps %s of %s did not pass in the pipeline %s on the branch %s, at the commit %s. The module's next passed pipeline on the branch clears this.",
strings.Join(names, ", "), m.Module, p.Pipeline, p.Branch, m.Commit)
if why != "" {
explanation += " " + why
}
err := f.Findings.Write(ctx, condseat.Finding{Scope: mcc.ScopeMerge, ID: m.Commit, Kind: PipelineFailedKind, Severity: condseat.FindingSeverityWarning,
Summary: fmt.Sprintf("%s on %s at %s: %s", m.Module, p.Branch, m.Commit, strings.Join(names, ", ")),
id := findingID(m.Module, p.Branch)
err := f.Findings.Write(ctx, condseat.Finding{Scope: mcc.ScopeDelivery, ID: id, Kind: PipelineFailedKind, Severity: condseat.FindingSeverityWarning,
Summary: fmt.Sprintf("%s on %s in %s: %s", m.Module, p.Branch, p.Pipeline, strings.Join(names, ", ")),
Headline: fmt.Sprintf("A required step of %s failed on %s", m.Module, p.Branch),
Explanation: explanation, Needs: "a newer commit of " + p.Branch + " that passes " + strings.Join(names, ", "),
Explanation: explanation, Needs: "a passed pipeline of " + m.Module + " on " + p.Branch,
Owner: owner, Source: "pipeline-runner." + PipelineFailedKind, Observer: f.Observer, At: now,
Subject: condseat.Subject{Scope: mcc.ScopeMerge, ID: m.Commit}})
Subject: condseat.Subject{Scope: mcc.ScopeDelivery, ID: id}})
if err != nil {
f.logf("the finding %s of %s at %s is not written: %v", PipelineFailedKind, m.Module, m.Commit, err)
f.logf("the finding %s of %s on %s is not written: %v", PipelineFailedKind, m.Module, p.Branch, err)
}
}
@@ -136,51 +154,3 @@ func (f *Failures) author(m seat.Mover) (string, string) {
}
return "forge:" + account, ""
}
// clearNewer clears the finding of each older pipeline of the branch moving m's module whose failed steps a newer one passed.
func (f *Failures) clearNewer(ctx context.Context, store Updater, p seat.Pipeline, m seat.Mover) {
pkeys, err := branchKeys(store, p.Branch)
if err != nil {
f.logf("the pipelines of %s on %s are not listed, so no finding %s is cleared: %v", m.Module, p.Branch, PipelineFailedKind, err)
return
}
var all []seat.Pipeline
for _, k := range pkeys {
if q, _, err := store.Get(k); err == nil && Moves(q, m.Module) {
all = append(all, q)
}
}
for _, old := range all {
was, _ := MoverOf(old, m.Module)
if old.Source >= p.Source || f.held(was.Commit) == nil {
continue
}
failed := failedSteps(old, m.Module)
if len(failed) == 0 {
continue
}
made := true
for _, s := range failed {
made = made && passedAfter(all, old, s)
}
if made {
if err := f.Findings.Clear(ctx, mcc.ScopeMerge, was.Commit, PipelineFailedKind, "a newer revision of "+p.Branch+" passes its steps"); err != nil {
f.logf("the finding %s of %s at %s is not cleared: %v", PipelineFailedKind, m.Module, was.Commit, err)
}
}
}
}
func passedAfter(all []seat.Pipeline, old seat.Pipeline, s seat.StepResult) bool {
for _, q := range all {
if q.Source <= old.Source {
continue
}
for _, t := range q.Steps {
if t.Module == s.Module && t.Artifact == s.Artifact && t.Step == s.Step && (t.Outcome == seat.StepResultOutcomePassed || t.Outcome == seat.StepResultOutcomeCarried) {
return true
}
}
}
return false
}
@@ -3,7 +3,6 @@ package pipeline
import (
"context"
"errors"
"strconv"
"strings"
"testing"
@@ -39,9 +38,10 @@ func (h *heldFindings) Held() []condseat.Finding {
return out
}
// A required step that failed or could not run is the finding pipeline-failed of its commit, owned by the commit's author as
// the forge records it; one whose author is not known has no owner and says why, and the next step end of that commit writes it
// (design 47 G §33, §540, A-191); an optional step that failed says nothing.
// A required step that failed or could not run is the finding pipeline-failed of its mover, id <module>.<branch> in the scope
// delivery, owned by the commit's author as the forge records it; one whose author is not known has no owner and says why, and
// the next step end of that mover writes it (design 47 G §33, §540, A-191; H §770, H-A-59); an optional step that failed says
// nothing.
func TestAFailedRequiredStepIsTheFindingOfItsCommit(t *testing.T) {
for _, c := range []struct {
name, step, outcome string
@@ -73,17 +73,17 @@ func TestAFailedRequiredStepIsTheFindingOfItsCommit(t *testing.T) {
if _, err := h.OnStepEnded(goSeat, goSeat.Prefix+"n1", ended(ask, c.step, c.outcome)); err != nil {
t.Fatal(err)
}
got, ok := f.held["merge.c1.pipeline-failed"]
got, ok := f.held["delivery.app.main.pipeline-failed"]
if ok != c.wantFinding {
t.Fatalf("finding written: %v, want %v (%v)", ok, c.wantFinding, f.held)
}
if !ok {
return
}
if got.Owner != c.wantOwner || got.Observer != "mesh-delivery-pipeline" || got.Subject.ID != "c1" {
if got.Owner != c.wantOwner || got.Observer != "mesh-delivery-pipeline" || got.Subject.ID != "app.main" {
t.Fatalf("finding %+v, want owner %q", got, c.wantOwner)
}
for _, name := range []string{"app", "main", "c1", "lint"} {
for _, name := range []string{"app", "main", "c1", "lint", pkey} {
if !strings.Contains(got.Explanation, name) {
t.Errorf("the explanation does not name %q: %s", name, got.Explanation)
}
@@ -109,7 +109,7 @@ func TestTheOwnerOfAFailedHeadIsWrittenAtTheNextStepEnd(t *testing.T) {
if _, err := h.OnStepEnded(goSeat, goSeat.Prefix+"n1", ended("a1", "lint", "failed")); err != nil {
t.Fatal(err)
}
if f.held["merge.c1.pipeline-failed"].Owner != "" {
if f.held["delivery.app.main.pipeline-failed"].Owner != "" {
t.Fatalf("an owner before the author is known: %+v", f.held)
}
known = true
@@ -119,48 +119,41 @@ func TestTheOwnerOfAFailedHeadIsWrittenAtTheNextStepEnd(t *testing.T) {
if _, err := h.OnStepEnded(goSeat, goSeat.Prefix+"n1", ended("a2", "unit", "failed")); err != nil {
t.Fatal(err)
}
if got := f.held["merge.c1.pipeline-failed"].Owner; got != "forge:bob" {
if got := f.held["delivery.app.main.pipeline-failed"].Owner; got != "forge:bob" {
t.Fatalf("owner %q, want forge:bob", got)
}
}
// A newer revision of the branch passing the step that failed clears the finding of the older commit; one that does not pass
// it, and a newer head failing on its own, leave it, and the newer failing head is a finding of its own (§33, §540).
func TestANewerPassingRevisionClearsTheFinding(t *testing.T) {
h, store, _, _, _, _ := fixture()
// R15/AC1 (design 47 H §770): a pipeline with two failing movers raises two findings, one per mover, id <module>.<branch>;
// a later pipeline passing one of them clears that one alone.
func TestEachFailingMoverIsAFindingAndItsNextPassedPipelineClearsIt(t *testing.T) {
h, store, _, _ := twoMovers(t)
f := newHeld()
h.Failures = &Failures{Findings: f, Now: h.Now, Author: func(string, string) (string, error) { return "alice", nil }}
if _, err := h.OnStepEnded(goSeat, goSeat.Prefix+"n1", ended("a1", "lint", "failed")); err != nil {
t.Fatal(err)
for _, ev := range []StepEnded{ended("a1", "lint", "failed"), libEnded("failed")} {
if _, err := h.OnStepEnded(goSeat, goSeat.Prefix+"n1", ev); err != nil {
t.Fatal(err)
}
}
newer := func(source int64, commit, ask string) string {
key := "main." + strconv.FormatInt(source, 10)
store[key] = struct {
p seat.Pipeline
rev uint64
}{seat.Pipeline{V: 1, Pipeline: key, Branch: "main", Source: source,
Outcome: seat.PipelineOutcomeRunning, Steps: []seat.StepResult{{Module: "app", Artifact: "program", Step: seat.StepResultStepLint,
Status: seat.StepResultStatusRequired, Outcome: seat.StepResultOutcomeRunning, Ask: ask, Seat: nodebuildgo.Seat}}, Movers: []seat.Mover{{Module: "app", Commit: commit, Fingerprint: "src2:aa"}}}, 1}
return key
if _, ok := f.held["delivery.app.main.pipeline-failed"]; !ok || len(f.held) != 2 {
t.Fatalf("findings %v, want one for app and one for lib", f.held)
}
// A newer head that fails the step too is a finding of its own, and the older one stays.
key := newer(6, "c2", "b1")
ev := ended("b1", "lint", "failed")
ev.Pipeline, ev.Commit = key, "c2"
if lib := f.held["delivery.lib.main.pipeline-failed"]; !strings.Contains(lib.Explanation, pkey) || !strings.Contains(lib.Summary, "unit") {
t.Errorf("lib's finding %+v, want the pipeline and the step named", lib)
}
// A later pipeline moving lib alone passes: lib's finding clears, app's stands.
store["main.6"] = struct {
p seat.Pipeline
rev uint64
}{seat.Pipeline{V: 1, Pipeline: "main.6", Branch: "main", Source: 6, Outcome: seat.PipelineOutcomeRunning,
Steps: []seat.StepResult{{Module: "lib", Artifact: "lib:lib", Step: seat.StepResultStepUnit, Status: seat.StepResultStatusRequired,
Outcome: seat.StepResultOutcomeRunning, Ask: "b2", Seat: nodebuildgo.Seat}}, Movers: []seat.Mover{{Module: "lib", Commit: "c4", Fingerprint: "src2:dd"}}}, 1}
ev := libEnded("passed")
ev.ID, ev.Ask, ev.Pipeline, ev.Commit, ev.Fingerprint = "b2", "b2", "main.6", "c4", "src2:dd"
if _, err := h.OnStepEnded(goSeat, goSeat.Prefix+"n1", ev); err != nil {
t.Fatal(err)
}
if _, ok := f.held["merge.c1.pipeline-failed"]; !ok || len(f.held) != 2 {
t.Fatalf("findings %v, want c1 and c2", f.held)
}
// A newest head passing it clears both older commits' findings.
key = newer(7, "c3", "b2")
ev = ended("b2", "lint", "passed")
ev.Pipeline, ev.Commit = key, "c3"
if _, err := h.OnStepEnded(goSeat, goSeat.Prefix+"n1", ev); err != nil {
t.Fatal(err)
}
if len(f.held) != 0 {
t.Fatalf("findings %v stand after a newer revision passed the step", f.held)
if _, stands := f.held["delivery.app.main.pipeline-failed"]; !stands || len(f.held) != 1 {
t.Fatalf("findings %v, want app's alone after lib's pipeline passed", f.held)
}
}
@@ -412,6 +412,7 @@ func (h *Hearer) said(p seat.Pipeline, asked []int, ended bool) error {
}
}
if ended {
h.Failures.Ended(p)
if err := h.say(seat.EventPipelineEnded, p, nil); err != nil {
return fmt.Errorf("pipeline %s ended but %s is not said: %w", p.Pipeline, seat.EventPipelineEnded, err)
}