tenseleyflow/shithub / f0bdb52

+// SPDX-License-Identifier: AGPL-3.0-or-later

+

+// Package checks owns CI check-suite + check-run orchestration. The

+// API layer (internal/web/handlers/api/checks.go) calls into Create

+// and Update; the merge gate at internal/pulls/pulls.go calls

+// EvaluateRequiredChecks.

+//

+// No work in this package executes user code — shithub is a

+// receiver of check status from external systems (and, post-MVP,

+// shithub Actions). The API surface is GitHub-shaped so existing CI

+// adapters port cleanly.

+package checks

+

+import (

+	"errors"

+	"log/slog"

+

+	"github.com/jackc/pgx/v5/pgxpool"

+)

+

+// Deps wires the package against the runtime.

+type Deps struct {

+	Pool   *pgxpool.Pool

+	Logger *slog.Logger

+}

+

+// Output is the JSON shape stored in `check_runs.output`. Matches

+// GitHub's `output` shape: title + summary + text. Bodies are bounded

+// at the orchestrator (256 KiB on text, 64 KiB on summary) per spec.

+type Output struct {

+	Title   string `json:"title,omitempty"`

+	Summary string `json:"summary,omitempty"`

+	Text    string `json:"text,omitempty"`

+}

+

+// MaxOutputTextBytes / MaxOutputSummaryBytes cap the output payload

+// per spec section "Open questions".

+const (

+	MaxOutputTextBytes    = 256 * 1024

+	MaxOutputSummaryBytes = 64 * 1024

+)

+

+// Errors surfaced to API + handlers.

+var (

+	ErrEmptyName              = errors.New("checks: name is required")

+	ErrNameTooLong            = errors.New("checks: name too long (max 200)")

+	ErrInvalidStatus          = errors.New("checks: status must be queued, in_progress, completed, or pending")

+	ErrInvalidConclusion      = errors.New("checks: invalid conclusion")

+	ErrCompletedNeedsConclusion = errors.New("checks: completed status requires conclusion")

+	ErrOutputTextTooLarge     = errors.New("checks: output.text exceeds 256 KiB cap")

+	ErrOutputSummaryTooLarge  = errors.New("checks: output.summary exceeds 64 KiB cap")

+	ErrShortHeadSHA           = errors.New("checks: head_sha must be at least 7 hex chars")

+	ErrCheckRunNotFound       = errors.New("checks: run not found")

+	ErrSuiteNotFound          = errors.New("checks: suite not found")

+)

+

+// validStatus / validConclusion mirror the Postgres enums.

+func validStatus(s string) bool {

+	switch s {

+	case "queued", "in_progress", "completed", "pending":

+		return true

+	}

+	return false

+}

+

+func validConclusion(s string) bool {

+	switch s {

+	case "success", "failure", "neutral", "cancelled",

+		"skipped", "timed_out", "action_required", "stale":

+		return true

+	}

+	return false

+}

+// SPDX-License-Identifier: AGPL-3.0-or-later

+

+package checks_test

+

+import (

+	"context"

+	"io"

+	"log/slog"

+	"strings"

+	"testing"

+	"time"

+

+	"github.com/jackc/pgx/v5/pgtype"

+	"github.com/jackc/pgx/v5/pgxpool"

+

+	"github.com/tenseleyFlow/shithub/internal/checks"

+	checksdb "github.com/tenseleyFlow/shithub/internal/checks/sqlc"

+	reposdb "github.com/tenseleyFlow/shithub/internal/repos/sqlc"

+	"github.com/tenseleyFlow/shithub/internal/testing/dbtest"

+	usersdb "github.com/tenseleyFlow/shithub/internal/users/sqlc"

+)

+

+const fixtureHash = "$argon2id$v=19$m=16384,t=1,p=1$" +

+	"AAAAAAAAAAAAAAAA$" +

+	"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"

+

+type fx struct {

+	pool   *pgxpool.Pool

+	deps   checks.Deps

+	repoID int64

+}

+

+func setup(t *testing.T) fx {

+	t.Helper()

+	pool := dbtest.NewTestDB(t)

+	ctx := context.Background()

+

+	user, err := usersdb.New().CreateUser(ctx, pool, usersdb.CreateUserParams{

+		Username: "alice", DisplayName: "Alice", PasswordHash: fixtureHash,

+	})

+	if err != nil {

+		t.Fatalf("CreateUser: %v", err)

+	}

+	repo, err := reposdb.New().CreateRepo(ctx, pool, reposdb.CreateRepoParams{

+		OwnerUserID:   pgtype.Int8{Int64: user.ID, Valid: true},

+		Name:          "demo",

+		DefaultBranch: "trunk",

+		Visibility:    reposdb.RepoVisibilityPublic,

+	})

+	if err != nil {

+		t.Fatalf("CreateRepo: %v", err)

+	}

+	return fx{

+		pool:   pool,

+		deps:   checks.Deps{Pool: pool, Logger: slog.New(slog.NewTextHandler(io.Discard, nil))},

+		repoID: repo.ID,

+	}

+}

+

+func TestCreate_AutoCreatesSuite(t *testing.T) {

+	f := setup(t)

+	ctx := context.Background()

+	run, err := checks.Create(ctx, f.deps, checks.CreateParams{

+		RepoID:  f.repoID,

+		HeadSHA: strings.Repeat("a", 40),

+		Name:    "lint",

+	})

+	if err != nil {

+		t.Fatalf("Create: %v", err)

+	}

+	if run.SuiteID == 0 {

+		t.Errorf("SuiteID should be set")

+	}

+	if run.Status != checksdb.CheckStatusQueued {

+		t.Errorf("default status: got %s, want queued", run.Status)

+	}

+	suites, _ := checksdb.New().ListCheckSuitesForCommit(ctx, f.pool, checksdb.ListCheckSuitesForCommitParams{

+		RepoID: f.repoID, HeadSha: run.HeadSha,

+	})

+	if len(suites) != 1 || suites[0].AppSlug != "external" {

+		t.Errorf("expected one external suite, got %v", suites)

+	}

+}

+

+func TestCreate_IdempotentByExternalID(t *testing.T) {

+	f := setup(t)

+	ctx := context.Background()

+	args := checks.CreateParams{

+		RepoID:     f.repoID,

+		HeadSHA:    strings.Repeat("a", 40),

+		Name:       "lint",

+		ExternalID: "ci-job-42",

+	}

+	a, err := checks.Create(ctx, f.deps, args)

+	if err != nil {

+		t.Fatalf("first Create: %v", err)

+	}

+	b, err := checks.Create(ctx, f.deps, args)

+	if err != nil {

+		t.Fatalf("second Create: %v", err)

+	}

+	if a.ID != b.ID {

+		t.Errorf("expected same id (idempotent), got %d vs %d", a.ID, b.ID)

+	}

+}

+

+func TestCreate_RequiresConclusionWhenCompleted(t *testing.T) {

+	f := setup(t)

+	_, err := checks.Create(context.Background(), f.deps, checks.CreateParams{

+		RepoID:  f.repoID,

+		HeadSHA: strings.Repeat("a", 40),

+		Name:    "lint",

+		Status:  "completed",

+	})

+	if err == nil {

+		t.Errorf("expected ErrCompletedNeedsConclusion, got nil")

+	}

+}

+

+func TestCreate_RejectsShortHeadSHA(t *testing.T) {

+	f := setup(t)

+	_, err := checks.Create(context.Background(), f.deps, checks.CreateParams{

+		RepoID:  f.repoID,

+		HeadSHA: "abc",

+		Name:    "lint",

+	})

+	if err == nil {

+		t.Errorf("expected ErrShortHeadSHA, got nil")

+	}

+}

+

+func TestCreate_RejectsTooLargeOutput(t *testing.T) {

+	f := setup(t)

+	big := strings.Repeat("x", checks.MaxOutputTextBytes+1)

+	_, err := checks.Create(context.Background(), f.deps, checks.CreateParams{

+		RepoID:  f.repoID,

+		HeadSHA: strings.Repeat("a", 40),

+		Name:    "lint",

+		Output:  checks.Output{Text: big},

+	})

+	if err == nil {

+		t.Errorf("expected ErrOutputTextTooLarge, got nil")

+	}

+}

+

+func TestUpdate_RollsUpSuiteConclusion(t *testing.T) {

+	f := setup(t)

+	ctx := context.Background()

+	sha := strings.Repeat("a", 40)

+	a, _ := checks.Create(ctx, f.deps, checks.CreateParams{

+		RepoID: f.repoID, HeadSHA: sha, Name: "lint",

+	})

+	b, _ := checks.Create(ctx, f.deps, checks.CreateParams{

+		RepoID: f.repoID, HeadSHA: sha, Name: "test",

+	})

+	// Complete both as success.

+	for _, id := range []int64{a.ID, b.ID} {

+		if _, err := checks.Update(ctx, f.deps, checks.UpdateParams{

+			RunID:         id,

+			HasStatus:     true,

+			Status:        "completed",

+			HasConclusion: true,

+			Conclusion:    "success",

+		}); err != nil {

+			t.Fatalf("Update %d: %v", id, err)

+		}

+	}

+	suite, _ := checksdb.New().GetCheckSuite(ctx, f.pool, a.SuiteID)

+	if suite.Status != checksdb.CheckStatusCompleted {

+		t.Errorf("suite status: got %s, want completed", suite.Status)

+	}

+	if !suite.Conclusion.Valid || suite.Conclusion.CheckConclusion != checksdb.CheckConclusionSuccess {

+		t.Errorf("suite conclusion: got %+v, want success", suite.Conclusion)

+	}

+}

+

+func TestEvaluateRequiredChecks_NoRequired(t *testing.T) {

+	f := setup(t)

+	got, err := checks.EvaluateRequiredChecks(context.Background(), f.pool, checks.GateInputs{

+		RepoID: f.repoID, HeadSHA: strings.Repeat("a", 40),

+	})

+	if err != nil || !got.Satisfied {

+		t.Errorf("no required → satisfied; got %+v err=%v", got, err)

+	}

+}

+

+func TestEvaluateRequiredChecks_BlocksThenSatisfies(t *testing.T) {

+	f := setup(t)

+	ctx := context.Background()

+	sha := strings.Repeat("a", 40)

+	in := checks.GateInputs{

+		RepoID:        f.repoID,

+		HeadSHA:       sha,

+		RequiredNames: []string{"lint"},

+	}

+

+	// No run yet → blocked.

+	got, _ := checks.EvaluateRequiredChecks(ctx, f.pool, in)

+	if got.Satisfied {

+		t.Errorf("no run yet, expected blocked")

+	}

+	// Queued run → still blocked.

+	run, _ := checks.Create(ctx, f.deps, checks.CreateParams{

+		RepoID: f.repoID, HeadSHA: sha, Name: "lint",

+	})

+	got, _ = checks.EvaluateRequiredChecks(ctx, f.pool, in)

+	if got.Satisfied {

+		t.Errorf("queued run, expected blocked")

+	}

+	// Complete with failure → still blocked.

+	_, _ = checks.Update(ctx, f.deps, checks.UpdateParams{

+		RunID: run.ID, HasStatus: true, Status: "completed",

+		HasConclusion: true, Conclusion: "failure",

+	})

+	got, _ = checks.EvaluateRequiredChecks(ctx, f.pool, in)

+	if got.Satisfied {

+		t.Errorf("failure, expected blocked")

+	}

+	// Switch to success → satisfied.

+	_, _ = checks.Update(ctx, f.deps, checks.UpdateParams{

+		RunID: run.ID, HasStatus: true, Status: "completed",

+		HasConclusion: true, Conclusion: "success",

+	})

+	got, _ = checks.EvaluateRequiredChecks(ctx, f.pool, in)

+	if !got.Satisfied {

+		t.Errorf("success, expected satisfied; reason=%q missing=%v", got.Reason, got.Missing)

+	}

+}

+

+func TestStaleOnPush_MarksSuites(t *testing.T) {

+	f := setup(t)

+	ctx := context.Background()

+	prev := strings.Repeat("a", 40)

+	// Queue a run on prev → suite status=queued.

+	if _, err := checks.Create(ctx, f.deps, checks.CreateParams{

+		RepoID: f.repoID, HeadSHA: prev, Name: "lint",

+	}); err != nil {

+		t.Fatalf("Create: %v", err)

+	}

+	n, err := checks.MarkStaleForPreviousHead(ctx, f.deps, f.repoID, prev)

+	if err != nil {

+		t.Fatalf("MarkStaleForPreviousHead: %v", err)

+	}

+	if n != 1 {

+		t.Errorf("expected 1 suite marked stale, got %d", n)

+	}

+	suites, _ := checksdb.New().ListCheckSuitesForCommit(ctx, f.pool, checksdb.ListCheckSuitesForCommitParams{

+		RepoID: f.repoID, HeadSha: prev,

+	})

+	if len(suites) != 1 || !suites[0].Conclusion.Valid ||

+		suites[0].Conclusion.CheckConclusion != checksdb.CheckConclusionStale {

+		t.Errorf("post-stale: %+v", suites)

+	}

+}

+

+func TestUpdate_TimestampsRoundTrip(t *testing.T) {

+	f := setup(t)

+	ctx := context.Background()

+	when := time.Date(2026, 5, 8, 12, 0, 0, 0, time.UTC)

+	run, _ := checks.Create(ctx, f.deps, checks.CreateParams{

+		RepoID: f.repoID, HeadSHA: strings.Repeat("a", 40), Name: "lint",

+	})

+	if _, err := checks.Update(ctx, f.deps, checks.UpdateParams{

+		RunID:          run.ID,

+		HasStatus:      true, Status: "completed",

+		HasConclusion:  true, Conclusion: "success",

+		HasStartedAt:   true, StartedAt: when,

+		HasCompletedAt: true, CompletedAt: when.Add(30 * time.Second),

+	}); err != nil {

+		t.Fatalf("Update: %v", err)

+	}

+	got, _ := checksdb.New().GetCheckRun(ctx, f.pool, run.ID)

+	if !got.StartedAt.Valid || !got.CompletedAt.Valid {

+		t.Errorf("timestamps not set: %+v", got)

+	}

+}

+// SPDX-License-Identifier: AGPL-3.0-or-later

+

+package checks

+

+import (

+	"context"

+	"encoding/json"

+	"errors"

+	"fmt"

+	"strings"

+	"time"

+

+	"github.com/jackc/pgx/v5"

+	"github.com/jackc/pgx/v5/pgtype"

+

+	checksdb "github.com/tenseleyFlow/shithub/internal/checks/sqlc"

+)

+

+// CreateParams describes a check-run create request. Defaults

+// (per spec): status='queued', app_slug='external'.

+type CreateParams struct {

+	RepoID      int64

+	HeadSHA     string

+	AppSlug     string // "" → "external"

+	Name        string

+	Status      string // "" → "queued"

+	Conclusion  string // optional

+	StartedAt   time.Time

+	CompletedAt time.Time

+	DetailsURL  string

+	Output      Output

+	ExternalID  string // optional; enables idempotent retry-create

+}

+

+// Create inserts (or returns existing-by-external-id) a check run,

+// auto-creating the matching suite. Suite rollup is recomputed inside

+// the same tx so the API response reflects the latest derived state.

+//

+// `external_id` semantics:

+//   - When empty: always insert a new run.

+//   - When non-empty: lookup by (repo, head_sha, name, external_id);

+//     if found, return existing without insert. This makes retries

+//     by external CI safe.

+func Create(ctx context.Context, deps Deps, p CreateParams) (checksdb.CheckRun, error) {

+	if err := validateCreate(&p); err != nil {

+		return checksdb.CheckRun{}, err

+	}

+	q := checksdb.New()

+

+	// Idempotency check.

+	if p.ExternalID != "" {

+		existing, err := q.GetCheckRunByExternalID(ctx, deps.Pool, checksdb.GetCheckRunByExternalIDParams{

+			RepoID:     p.RepoID,

+			HeadSha:    p.HeadSHA,

+			Name:       p.Name,

+			ExternalID: pgtype.Text{String: p.ExternalID, Valid: true},

+		})

+		if err == nil {

+			return existing, nil

+		}

+		if !errors.Is(err, pgx.ErrNoRows) {

+			return checksdb.CheckRun{}, err

+		}

+	}

+

+	tx, err := deps.Pool.Begin(ctx)

+	if err != nil {

+		return checksdb.CheckRun{}, err

+	}

+	committed := false

+	defer func() {

+		if !committed {

+			_ = tx.Rollback(ctx)

+		}

+	}()

+

+	suite, err := q.GetOrCreateCheckSuite(ctx, tx, checksdb.GetOrCreateCheckSuiteParams{

+		RepoID:   p.RepoID,

+		HeadSha:  p.HeadSHA,

+		AppSlug:  p.AppSlug,

+	})

+	if err != nil {

+		return checksdb.CheckRun{}, fmt.Errorf("suite: %w", err)

+	}

+

+	outputJSON, err := json.Marshal(p.Output)

+	if err != nil {

+		return checksdb.CheckRun{}, fmt.Errorf("output marshal: %w", err)

+	}

+

+	startedAt := pgtype.Timestamptz{}

+	if !p.StartedAt.IsZero() {

+		startedAt = pgtype.Timestamptz{Time: p.StartedAt, Valid: true}

+	}

+	completedAt := pgtype.Timestamptz{}

+	if !p.CompletedAt.IsZero() {

+		completedAt = pgtype.Timestamptz{Time: p.CompletedAt, Valid: true}

+	}

+	conclusion := checksdb.NullCheckConclusion{}

+	if p.Conclusion != "" {

+		conclusion = checksdb.NullCheckConclusion{

+			CheckConclusion: checksdb.CheckConclusion(p.Conclusion),

+			Valid:           true,

+		}

+	}

+	extID := pgtype.Text{}

+	if p.ExternalID != "" {

+		extID = pgtype.Text{String: p.ExternalID, Valid: true}

+	}

+

+	run, err := q.CreateCheckRun(ctx, tx, checksdb.CreateCheckRunParams{

+		SuiteID:     suite.ID,

+		RepoID:      p.RepoID,

+		HeadSha:     p.HeadSHA,

+		Name:        p.Name,

+		Status:      checksdb.CheckStatus(p.Status),

+		Conclusion:  conclusion,

+		StartedAt:   startedAt,

+		CompletedAt: completedAt,

+		DetailsUrl:  p.DetailsURL,

+		Output:      outputJSON,

+		ExternalID:  extID,

+	})

+	if err != nil {

+		return checksdb.CheckRun{}, fmt.Errorf("insert run: %w", err)

+	}

+

+	if err := rollupSuiteInTx(ctx, tx, suite.ID); err != nil {

+		return checksdb.CheckRun{}, err

+	}

+

+	if err := tx.Commit(ctx); err != nil {

+		return checksdb.CheckRun{}, err

+	}

+	committed = true

+	return run, nil

+}

+

+// validateCreate normalizes defaults + applies per-field bounds.

+func validateCreate(p *CreateParams) error {

+	p.Name = strings.TrimSpace(p.Name)

+	if p.Name == "" {

+		return ErrEmptyName

+	}

+	if len(p.Name) > 200 {

+		return ErrNameTooLong

+	}

+	p.HeadSHA = strings.TrimSpace(p.HeadSHA)

+	if len(p.HeadSHA) < 7 || len(p.HeadSHA) > 64 {

+		return ErrShortHeadSHA

+	}

+	p.AppSlug = strings.TrimSpace(p.AppSlug)

+	if p.AppSlug == "" {

+		p.AppSlug = "external"

+	}

+	p.Status = strings.TrimSpace(p.Status)

+	if p.Status == "" {

+		p.Status = "queued"

+	}

+	if !validStatus(p.Status) {

+		return ErrInvalidStatus

+	}

+	if p.Conclusion != "" && !validConclusion(p.Conclusion) {

+		return ErrInvalidConclusion

+	}

+	if p.Status == "completed" && p.Conclusion == "" {

+		return ErrCompletedNeedsConclusion

+	}

+	if len(p.Output.Text) > MaxOutputTextBytes {

+		return ErrOutputTextTooLarge

+	}

+	if len(p.Output.Summary) > MaxOutputSummaryBytes {

+		return ErrOutputSummaryTooLarge

+	}

+	return nil

+}

+// SPDX-License-Identifier: AGPL-3.0-or-later

+

+package checks

+

+import (

+	"context"

+	"errors"

+	"fmt"

+

+	"github.com/jackc/pgx/v5"

+	"github.com/jackc/pgx/v5/pgxpool"

+

+	checksdb "github.com/tenseleyFlow/shithub/internal/checks/sqlc"

+)

+

+// GateInputs is the small struct the merge gate cares about.

+type GateInputs struct {

+	RepoID         int64

+	HeadSHA        string

+	RequiredNames  []string // from branch_protection_rules.status_checks_required

+}

+

+// GateResult mirrors the spec's blocked-with-reason vocabulary.

+type GateResult struct {

+	Satisfied bool

+	Reason    string  // "" when Satisfied; otherwise human-readable cause

+	// Missing is the subset of RequiredNames that haven't yet succeeded

+	// or returned neutral on HeadSHA. Populated for UI tooltips.

+	Missing []string

+}

+

+// EvaluateRequiredChecks returns Satisfied=true when every required

+// check name has a `success` or `neutral` conclusion on HeadSHA. A

+// missing run, an in-progress run, or any other conclusion (failure /

+// stale / cancelled / etc.) is unsatisfied.

+//

+// The evaluator is the same one consulted by `pulls.Mergeability` and

+// `pulls.Merge` — composes with `review.Evaluate` at the call site.

+func EvaluateRequiredChecks(ctx context.Context, pool *pgxpool.Pool, in GateInputs) (GateResult, error) {

+	if len(in.RequiredNames) == 0 {

+		return GateResult{Satisfied: true}, nil

+	}

+	if in.HeadSHA == "" {

+		// No head snapshot yet — block, since we can't verify any check

+		// passed against an unknown commit.

+		return GateResult{

+			Reason:  "head SHA not yet recorded for this PR",

+			Missing: append([]string(nil), in.RequiredNames...),

+		}, nil

+	}

+	q := checksdb.New()

+	missing := []string{}

+	for _, name := range in.RequiredNames {

+		run, err := q.GetLatestCheckRunByName(ctx, pool, checksdb.GetLatestCheckRunByNameParams{

+			RepoID:  in.RepoID,

+			HeadSha: in.HeadSHA,

+			Name:    name,

+		})

+		if err != nil {

+			if errors.Is(err, pgx.ErrNoRows) {

+				missing = append(missing, name)

+				continue

+			}

+			return GateResult{}, fmt.Errorf("required-check lookup %q: %w", name, err)

+		}

+		if !runSatisfies(run) {

+			missing = append(missing, name)

+		}

+	}

+	if len(missing) == 0 {

+		return GateResult{Satisfied: true}, nil

+	}

+	reason := "Required check missing: " + missing[0]

+	if len(missing) > 1 {

+		reason = fmt.Sprintf("Required checks missing: %v", missing)

+	}

+	return GateResult{Reason: reason, Missing: missing}, nil

+}

+

+// runSatisfies reports whether a single run "passes" for the

+// required-check gate. Matches the spec: `success` and `neutral` on

+// the head SHA satisfy; anything else (including in_progress) does

+// not.

+func runSatisfies(r checksdb.CheckRun) bool {

+	if r.Status != checksdb.CheckStatusCompleted {

+		return false

+	}

+	if !r.Conclusion.Valid {

+		return false

+	}

+	switch r.Conclusion.CheckConclusion {

+	case checksdb.CheckConclusionSuccess, checksdb.CheckConclusionNeutral:

+		return true

+	}

+	return false

+}

+// SPDX-License-Identifier: AGPL-3.0-or-later

+

+package checks

+

+import (

+	"context"

+

+	checksdb "github.com/tenseleyFlow/shithub/internal/checks/sqlc"

+)

+

+// MarkStaleForPreviousHead flips suites on `prevHeadSHA` whose status

+// is not yet completed to (completed, conclusion='stale'). Called from

+// push:process when a head ref moves AND the matching protection rule

+// has `dismiss_stale_status_checks_on_push = true`.

+//

+// "Status complete + conclusion stale" preserves the audit trail —

+// the runs themselves stay readable, but the suite no longer counts

+// as in-progress.

+func MarkStaleForPreviousHead(ctx context.Context, deps Deps, repoID int64, prevHeadSHA string) (int, error) {

+	if prevHeadSHA == "" {

+		return 0, nil

+	}

+	q := checksdb.New()

+	ids, err := q.ListCheckSuiteIDsForHead(ctx, deps.Pool, checksdb.ListCheckSuiteIDsForHeadParams{

+		RepoID: repoID, HeadSha: prevHeadSHA,

+	})

+	if err != nil {

+		return 0, err

+	}

+	for _, id := range ids {

+		if err := q.MarkCheckSuiteStale(ctx, deps.Pool, id); err != nil {

+			return 0, err

+		}

+	}

+	return len(ids), nil

+}

+// SPDX-License-Identifier: AGPL-3.0-or-later

+

+package checks

+

+import (

+	"context"

+

+	"github.com/jackc/pgx/v5"

+

+	checksdb "github.com/tenseleyFlow/shithub/internal/checks/sqlc"

+)

+

+// rollupSuiteInTx recomputes the suite's status + conclusion from its

+// runs and persists the result. Called from Create and Update inside

+// the same tx so the API response reflects the latest derived state.

+//

+// Per spec design table:

+//

+//	status = 'completed' iff every run is completed

+//	conclusion priority (when status='completed'):

+//	    failure         > timed_out > cancelled > action_required >

+//	    success         > neutral > skipped     > stale

+//

+// The "first failure-class wins" ordering matches GitHub's roll-up.

+// Any non-completed run forces status to 'in_progress' (or keeps the

+// existing 'queued' if every run is queued — we treat queued+completed

+// as 'in_progress' too, since *something* moved).

+func rollupSuiteInTx(ctx context.Context, tx pgx.Tx, suiteID int64) error {

+	q := checksdb.New()

+	runs, err := q.ListCheckRunsBySuite(ctx, tx, suiteID)

+	if err != nil {

+		return err

+	}

+	status, conclusion := DeriveSuiteRollup(runs)

+	conclusionParam := checksdb.NullCheckConclusion{}

+	if conclusion != "" {

+		conclusionParam = checksdb.NullCheckConclusion{

+			CheckConclusion: checksdb.CheckConclusion(conclusion),

+			Valid:           true,

+		}

+	}

+	return q.UpdateCheckSuiteRollup(ctx, tx, checksdb.UpdateCheckSuiteRollupParams{

+		ID:         suiteID,

+		Status:     checksdb.CheckStatus(status),

+		Conclusion: conclusionParam,

+	})

+}

+

+// DeriveSuiteRollup is the pure-function form of the rollup so tests

+// can exercise the priority order without a DB. Public so the API

+// layer can preview the rollup if needed.

+func DeriveSuiteRollup(runs []checksdb.CheckRun) (status, conclusion string) {

+	if len(runs) == 0 {

+		return "queued", ""

+	}

+	allCompleted := true

+	anyMoved := false

+	for _, r := range runs {

+		if r.Status != checksdb.CheckStatusCompleted {

+			allCompleted = false

+		}

+		if r.Status != checksdb.CheckStatusQueued {

+			anyMoved = true

+		}

+	}

+	if !allCompleted {

+		if anyMoved {

+			return "in_progress", ""

+		}

+		return "queued", ""

+	}

+	// Every run completed → derive aggregate conclusion.

+	priority := []string{

+		"failure", "timed_out", "cancelled", "action_required",

+		"success", "neutral", "skipped", "stale",

+	}

+	rank := map[string]int{}

+	for i, p := range priority {

+		rank[p] = i

+	}

+	bestIdx := -1

+	for _, r := range runs {

+		if !r.Conclusion.Valid {

+			continue

+		}

+		c := string(r.Conclusion.CheckConclusion)

+		idx, ok := rank[c]

+		if !ok {

+			continue

+		}

+		if bestIdx < 0 || idx < bestIdx {

+			bestIdx = idx

+		}

+	}

+	if bestIdx < 0 {

+		return "completed", "neutral"

+	}

+	return "completed", priority[bestIdx]

+}

+// SPDX-License-Identifier: AGPL-3.0-or-later

+

+package checks

+

+import (

+	"testing"

+

+	checksdb "github.com/tenseleyFlow/shithub/internal/checks/sqlc"

+)

+

+// run constructs a CheckRun with just the fields the rollup looks at.

+func run(status string, conclusion string) checksdb.CheckRun {

+	r := checksdb.CheckRun{Status: checksdb.CheckStatus(status)}

+	if conclusion != "" {

+		r.Conclusion = checksdb.NullCheckConclusion{

+			CheckConclusion: checksdb.CheckConclusion(conclusion),

+			Valid:           true,

+		}

+	}

+	return r

+}

+

+func TestDeriveSuiteRollup(t *testing.T) {

+	t.Parallel()

+	cases := []struct {

+		name        string

+		runs        []checksdb.CheckRun

+		wantStatus  string

+		wantConcl   string

+	}{

+		{

+			"empty → queued",

+			nil,

+			"queued", "",

+		},

+		{

+			"all queued → queued",

+			[]checksdb.CheckRun{run("queued", ""), run("queued", "")},

+			"queued", "",

+		},

+		{

+			"one in_progress → in_progress",

+			[]checksdb.CheckRun{run("queued", ""), run("in_progress", "")},

+			"in_progress", "",

+		},

+		{

+			"all completed success → success",

+			[]checksdb.CheckRun{run("completed", "success"), run("completed", "success")},

+			"completed", "success",

+		},

+		{

+			"any failure → failure",

+			[]checksdb.CheckRun{run("completed", "success"), run("completed", "failure")},

+			"completed", "failure",

+		},

+		{

+			"failure beats timed_out",

+			[]checksdb.CheckRun{run("completed", "timed_out"), run("completed", "failure")},

+			"completed", "failure",

+		},

+		{

+			"timed_out beats cancelled beats action_required",

+			[]checksdb.CheckRun{run("completed", "cancelled"), run("completed", "timed_out"), run("completed", "action_required")},

+			"completed", "timed_out",

+		},

+		{

+			"all neutral → neutral (no successes)",

+			[]checksdb.CheckRun{run("completed", "neutral"), run("completed", "neutral")},

+			"completed", "neutral",

+		},

+		{

+			"success beats neutral",

+			[]checksdb.CheckRun{run("completed", "success"), run("completed", "neutral")},

+			"completed", "success",

+		},

+		{

+			"all skipped → skipped",

+			[]checksdb.CheckRun{run("completed", "skipped"), run("completed", "skipped")},

+			"completed", "skipped",

+		},

+		{

+			"all stale → stale",

+			[]checksdb.CheckRun{run("completed", "stale")},

+			"completed", "stale",

+		},

+		{

+			"completed without conclusion → completed/neutral fallback",

+			[]checksdb.CheckRun{run("completed", "")},

+			"completed", "neutral",

+		},

+	}

+	for _, c := range cases {

+		t.Run(c.name, func(t *testing.T) {

+			gotStatus, gotConcl := DeriveSuiteRollup(c.runs)

+			if gotStatus != c.wantStatus || gotConcl != c.wantConcl {

+				t.Errorf("got (%s, %s), want (%s, %s)", gotStatus, gotConcl, c.wantStatus, c.wantConcl)

+			}

+		})

+	}

+}

+// SPDX-License-Identifier: AGPL-3.0-or-later

+

+package checks

+

+import (

+	"context"

+	"encoding/json"

+	"errors"

+	"fmt"

+	"strings"

+	"time"

+

+	"github.com/jackc/pgx/v5"

+	"github.com/jackc/pgx/v5/pgtype"

+

+	checksdb "github.com/tenseleyFlow/shithub/internal/checks/sqlc"

+)

+

+// UpdateParams describes a check-run patch. Empty optional fields

+// keep the existing value (rather than clearing); callers that want

+// to clear a field set it to the zero string explicitly via the

+// dedicated *Set boolean — keeps the JSON contract simple while

+// avoiding pointer-everywhere fields.

+//

+// Status transitions are validated: queued/pending → in_progress →

+// completed; completed requires a conclusion. Re-applying the same

+// status is a no-op, which makes external-system retries safe.

+type UpdateParams struct {

+	RunID       int64

+	Status      string

+	Conclusion  string

+	StartedAt   time.Time

+	CompletedAt time.Time

+	DetailsURL  string

+	Output      Output

+

+	HasStatus      bool

+	HasConclusion  bool

+	HasStartedAt   bool

+	HasCompletedAt bool

+	HasDetailsURL  bool

+	HasOutput      bool

+}

+

+// Update patches a check run + recomputes its suite's rollup. Fields

+// that aren't marked Has* keep their current value.

+func Update(ctx context.Context, deps Deps, p UpdateParams) (checksdb.CheckRun, error) {

+	q := checksdb.New()

+	cur, err := q.GetCheckRun(ctx, deps.Pool, p.RunID)

+	if err != nil {

+		if errors.Is(err, pgx.ErrNoRows) {

+			return checksdb.CheckRun{}, ErrCheckRunNotFound

+		}

+		return checksdb.CheckRun{}, err

+	}

+

+	// Resolve effective values.

+	status := string(cur.Status)

+	if p.HasStatus {

+		s := strings.TrimSpace(p.Status)

+		if !validStatus(s) {

+			return checksdb.CheckRun{}, ErrInvalidStatus

+		}

+		status = s

+	}

+	conclusion := ""

+	if cur.Conclusion.Valid {

+		conclusion = string(cur.Conclusion.CheckConclusion)

+	}

+	if p.HasConclusion {

+		c := strings.TrimSpace(p.Conclusion)

+		if c != "" && !validConclusion(c) {

+			return checksdb.CheckRun{}, ErrInvalidConclusion

+		}

+		conclusion = c

+	}

+	if status == "completed" && conclusion == "" {

+		return checksdb.CheckRun{}, ErrCompletedNeedsConclusion

+	}

+	startedAt := cur.StartedAt

+	if p.HasStartedAt {

+		if p.StartedAt.IsZero() {

+			startedAt = pgtype.Timestamptz{}

+		} else {

+			startedAt = pgtype.Timestamptz{Time: p.StartedAt, Valid: true}

+		}

+	}

+	completedAt := cur.CompletedAt

+	if p.HasCompletedAt {

+		if p.CompletedAt.IsZero() {

+			completedAt = pgtype.Timestamptz{}

+		} else {

+			completedAt = pgtype.Timestamptz{Time: p.CompletedAt, Valid: true}

+		}

+	}

+	detailsURL := cur.DetailsUrl

+	if p.HasDetailsURL {

+		detailsURL = p.DetailsURL

+	}

+	outputBytes := cur.Output

+	if p.HasOutput {

+		if len(p.Output.Text) > MaxOutputTextBytes {

+			return checksdb.CheckRun{}, ErrOutputTextTooLarge

+		}

+		if len(p.Output.Summary) > MaxOutputSummaryBytes {

+			return checksdb.CheckRun{}, ErrOutputSummaryTooLarge

+		}

+		outputBytes, err = json.Marshal(p.Output)

+		if err != nil {

+			return checksdb.CheckRun{}, fmt.Errorf("output marshal: %w", err)

+		}

+	}

+

+	tx, err := deps.Pool.Begin(ctx)

+	if err != nil {

+		return checksdb.CheckRun{}, err

+	}

+	committed := false

+	defer func() {

+		if !committed {

+			_ = tx.Rollback(ctx)

+		}

+	}()

+

+	conclusionParam := checksdb.NullCheckConclusion{}

+	if conclusion != "" {

+		conclusionParam = checksdb.NullCheckConclusion{

+			CheckConclusion: checksdb.CheckConclusion(conclusion),

+			Valid:           true,

+		}

+	}

+

+	if err := q.UpdateCheckRun(ctx, tx, checksdb.UpdateCheckRunParams{

+		ID:          p.RunID,

+		Status:      checksdb.CheckStatus(status),

+		Conclusion:  conclusionParam,

+		StartedAt:   startedAt,

+		CompletedAt: completedAt,

+		DetailsUrl:  detailsURL,

+		Output:      outputBytes,

+	}); err != nil {

+		return checksdb.CheckRun{}, fmt.Errorf("update run: %w", err)

+	}

+	if err := rollupSuiteInTx(ctx, tx, cur.SuiteID); err != nil {

+		return checksdb.CheckRun{}, err

+	}

+	if err := tx.Commit(ctx); err != nil {

+		return checksdb.CheckRun{}, err

+	}

+	committed = true

+

+	updated, err := q.GetCheckRun(ctx, deps.Pool, p.RunID)

+	if err != nil {

+		return checksdb.CheckRun{}, err

+	}

+	return updated, nil

+}