beads/internal/storage/issueops/aggregate.go
Julian Knutsen b92442d1a3
feat(storage): one guarded issue-lifecycle surface for the CLI and linked consumers (#5191)
Adds issueops.Lifecycle — Create, Update, Close, Reopen — reached from the storage handle via
store.IssueLifecycle(), implemented once and shared by the CLI and linked library consumers. Three backends
implement it and a shared conformance suite asserts them against one spec. The bd CLI's create, update,
close and reopen now route through it.

Fixes several defects that predate this change and became visible once the write paths were forced to
agree: swallowed metadata-edit failures, a claim applied before field validation, missing value validation
on title/priority/estimate, silently dropped create edges to missing targets, infra-typed creates landing in
the wrong table, a dropped SourceRepo, closed_by_session written but never read, and a compound update
writing twice.

Behavior changes needing release notes: create with an occupied explicit id now fails instead of silently
overwriting; a compound update is one atomic operation with one hook and one version commit; reparenting
replaces all parent edges; reopening something not closed reports nothing to do.
2026-07-31 11:26:38 -07:00

375 lines
12 KiB
Go

package issueops
import (
"context"
"database/sql"
"encoding/json"
"fmt"
"sort"
"strings"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/types"
publicops "github.com/steveyegge/beads/issueops"
)
// ChangedTables records durable tables changed by one guarded operation.
type ChangedTables map[string]bool
// Add records table names, ignoring empty names and wisp-only tables.
func (tables ChangedTables) Add(names ...string) {
for _, name := range names {
if name != "" && name != "wisps" && !strings.HasPrefix(name, "wisp_") {
tables[name] = true
}
}
}
// Merge records every table in other.
func (tables ChangedTables) Merge(other map[string]bool) {
for table := range other {
tables.Add(table)
}
}
// UpdateFields converts the public scalar patch fields to storage updates.
func UpdateFields(patch publicops.IssuePatch) map[string]interface{} {
updates := map[string]interface{}{}
for _, field := range []struct {
set bool
key string
val interface{}
}{
{patch.Title.Set, "title", patch.Title.Value},
{patch.Description.Set, "description", patch.Description.Value},
{patch.Design.Set, "design", patch.Design.Value},
{patch.AcceptanceCriteria.Set, "acceptance_criteria", patch.AcceptanceCriteria.Value},
{patch.Notes.Set, "notes", patch.Notes.Value},
{patch.AppendNotes.Set, "append_notes", patch.AppendNotes.Value},
{patch.SpecID.Set, "spec_id", patch.SpecID.Value},
{patch.AwaitID.Set, "await_id", patch.AwaitID.Value},
{patch.Status.Set, "status", patch.Status.Value},
{patch.Priority.Set, "priority", patch.Priority.Value},
{patch.IssueType.Set, "issue_type", patch.IssueType.Value},
{patch.Assignee.Set, "assignee", patch.Assignee.Value},
{patch.Owner.Set, "owner", patch.Owner.Value},
{patch.ClosedBySession.Set, "closed_by_session", patch.ClosedBySession.Value},
{patch.EstimatedMinutes.Set, "estimated_minutes", patch.EstimatedMinutes.Value},
{patch.ExternalRef.Set, "external_ref", patch.ExternalRef.Value},
{patch.DueAt.Set, "due_at", patch.DueAt.Value},
{patch.DeferUntil.Set, "defer_until", patch.DeferUntil.Value},
} {
if field.set {
updates[field.key] = field.val
}
}
return updates
}
// ValidateUpdateRequest checks mutually exclusive guarded-update options and
// the canonical field values every backend must reject identically. Backends
// call it before touching the row so an invalid patch cannot half-apply.
func ValidateUpdateRequest(request publicops.UpdateRequest) error {
if request.Claim && (request.ExpectedAssignee != nil || request.ExpectedStatus != nil) {
return fmt.Errorf("%w: claim cannot use expected assignee or status", storage.ErrValidation)
}
if request.ForceAssigneeTransfer && (request.Claim || !request.Patch.Assignee.Set || request.ExpectedAssignee != nil) {
return fmt.Errorf("%w: invalid forced assignee transfer", storage.ErrValidation)
}
patch := request.Patch
if patch.Title.Set {
if err := types.ValidateIssueTitle(patch.Title.Value); err != nil {
return fmt.Errorf("%w: update title: %w", storage.ErrValidation, err)
}
}
if patch.Priority.Set {
if err := types.ValidateIssuePriority(patch.Priority.Value); err != nil {
return fmt.Errorf("%w: update priority: %w", storage.ErrValidation, err)
}
}
if patch.EstimatedMinutes.Set {
if err := types.ValidateIssueEstimatedMinutes(patch.EstimatedMinutes.Value); err != nil {
return fmt.Errorf("%w: update estimated_minutes: %w", storage.ErrValidation, err)
}
}
if patch.Persistence.Set && !patch.Persistence.Value.IsValid() {
return fmt.Errorf("%w: invalid persistence mode %q", storage.ErrValidation, patch.Persistence.Value)
}
return nil
}
// ValidateMetadataPatch checks mutually exclusive metadata edits.
func ValidateMetadataPatch(patch publicops.MetadataPatch) error {
if patch.Replace.Set && (patch.Merge.Set || len(patch.Set) > 0 || len(patch.Unset) > 0) {
return fmt.Errorf("%w: cannot combine metadata replacement with incremental metadata edits", storage.ErrValidation)
}
return nil
}
// ValidateScalarUpdates checks typed scalar values before they reach SQL.
func ValidateScalarUpdates(ctx context.Context, tx DBTX, updates map[string]interface{}) error {
if rawType, ok := updates["issue_type"]; ok {
var issueType types.IssueType
switch value := rawType.(type) {
case types.IssueType:
issueType = value
case string:
issueType = types.IssueType(value)
default:
return fmt.Errorf("%w: invalid issue type %v", storage.ErrValidation, rawType)
}
customTypes, err := ResolveCustomTypesInTx(ctx, tx)
if err != nil {
return fmt.Errorf("resolve custom issue types: %w", err)
}
if !issueType.IsValidWithCustom(customTypes) {
return fmt.Errorf("%w: invalid issue type %s", storage.ErrValidation, issueType)
}
}
for _, field := range []string{"assignee", "owner"} {
if raw, ok := updates[field]; ok {
if value, ok := raw.(string); ok {
if err := types.CheckFieldLen(field, value); err != nil {
return err
}
}
}
}
return nil
}
// AuthorizeAssigneeTransfer protects an active assignment from unguarded transfer.
func AuthorizeAssigneeTransfer(ctx context.Context, tx DBTX, before *types.Issue, request publicops.UpdateRequest) error {
if !request.Patch.Assignee.Set || request.Patch.Assignee.Value == before.Assignee || request.ExpectedAssignee != nil || request.ForceAssigneeTransfer || before.Status != types.StatusInProgress || before.Assignee == "" || before.Assignee == request.Actor {
return nil
}
pools, err := ClaimPoolAliasesInTx(ctx, tx)
if err != nil {
return err
}
for _, pool := range pools {
if pool == before.Assignee {
return nil
}
}
return fmt.Errorf("%w: issue %s is assigned to %q", storage.ErrAlreadyClaimed, before.ID, before.Assignee)
}
// ApplyMetadataPatch returns the canonical metadata value and whether it changes.
func ApplyMetadataPatch(current json.RawMessage, patch publicops.MetadataPatch) (json.RawMessage, bool, error) {
if !patch.Replace.Set && !patch.Merge.Set && len(patch.Set) == 0 && len(patch.Unset) == 0 {
return current, false, nil
}
setKeys := make([]string, 0, len(patch.Set))
for key := range patch.Set {
setKeys = append(setKeys, key)
}
sort.Strings(setKeys)
for _, key := range setKeys {
if err := storage.ValidateMetadataKey(key); err != nil {
return nil, false, fmt.Errorf("%w: %w", storage.ErrValidation, err)
}
}
for _, key := range patch.Unset {
if err := storage.ValidateMetadataKey(key); err != nil {
return nil, false, fmt.Errorf("%w: %w", storage.ErrValidation, err)
}
}
var next json.RawMessage
if patch.Replace.Set {
next = append(json.RawMessage(nil), patch.Replace.Value...)
if len(next) == 0 {
next = json.RawMessage(`{}`)
}
if !json.Valid(next) {
return nil, false, fmt.Errorf("%w: metadata replacement is not valid JSON", storage.ErrValidation)
}
} else {
next = append(json.RawMessage(nil), current...)
if patch.Merge.Set {
// A JSON null unmarshals into a nil overlay map, so the merge
// below would silently accept it as "change nothing".
if strings.TrimSpace(string(patch.Merge.Value)) == "null" {
return nil, false, fmt.Errorf("%w: metadata merge must be a JSON object", storage.ErrValidation)
}
merged, err := storage.MergeMetadataJSON(next, patch.Merge.Value)
if err != nil {
return nil, false, fmt.Errorf("%w: metadata merge: %v", storage.ErrValidation, err)
}
next = merged
}
if len(patch.Set) > 0 || len(patch.Unset) > 0 {
values := make(map[string]json.RawMessage)
if len(next) > 0 && string(next) != "null" {
if err := json.Unmarshal(next, &values); err != nil {
return nil, false, fmt.Errorf("%w: metadata edits require an object: %v", storage.ErrValidation, err)
}
}
for _, key := range setKeys {
value := patch.Set[key]
if !json.Valid(value) {
return nil, false, fmt.Errorf("%w: metadata value for key %q is not valid JSON", storage.ErrValidation, key)
}
values[key] = append(json.RawMessage(nil), value...)
}
for _, key := range patch.Unset {
delete(values, key)
}
encoded, err := json.Marshal(values)
if err != nil {
return nil, false, fmt.Errorf("%w: encode metadata edits: %v", storage.ErrValidation, err)
}
next = encoded
}
}
if err := ValidateMetadataIfConfigured(next); err != nil {
return nil, false, err
}
changed, err := metadataChanged(current, next)
if err != nil {
return nil, false, fmt.Errorf("%w: compare metadata: %v", storage.ErrValidation, err)
}
return next, changed, nil
}
func metadataChanged(current, next json.RawMessage) (bool, error) {
canonical := func(raw json.RawMessage) (string, error) {
if len(raw) == 0 || string(raw) == "null" {
return "{}", nil
}
var value any
if err := json.Unmarshal(raw, &value); err != nil {
return "", err
}
encoded, err := json.Marshal(value)
return string(encoded), err
}
left, err := canonical(current)
if err != nil {
return false, err
}
right, err := canonical(next)
if err != nil {
return false, err
}
return left != right, nil
}
// ApplyLabelPatch applies ordered label edits and reports whether rows changed.
func ApplyLabelPatch(ctx context.Context, tx DBTX, current *types.Issue, patch publicops.LabelPatch, actor string) (bool, error) {
if !patch.Replace.Set && len(patch.Add) == 0 && len(patch.Remove) == 0 {
return false, nil
}
existing := stringSet(current.Labels)
target := make(map[string]struct{}, len(existing)+len(patch.Add))
if !patch.Replace.Set {
for label := range existing {
target[label] = struct{}{}
}
}
for _, label := range patch.Replace.Value {
target[label] = struct{}{}
}
for _, label := range patch.Add {
target[label] = struct{}{}
}
for _, label := range patch.Remove {
delete(target, label)
}
if sameStringSet(existing, target) {
return false, nil
}
sqlTx, ok := tx.(*sql.Tx)
if !ok {
return false, fmt.Errorf("apply labels: transaction must be *sql.Tx")
}
for _, label := range stringSetDifference(existing, target) {
if err := RemoveLabelInTx(ctx, sqlTx, "", "", current.ID, label, actor); err != nil {
return false, err
}
}
for _, label := range stringSetDifference(target, existing) {
if err := AddLabelInTx(ctx, sqlTx, "", "", current.ID, label, actor); err != nil {
return false, err
}
}
return true, nil
}
// ParentPatchResult reports the concrete changes made by ApplyParentPatch.
type ParentPatchResult struct {
Changed bool
IssueRowsChanged bool
WispRowsChanged bool
}
// ApplyParentPatch replaces the parent-child targets and reports concrete changes.
func ApplyParentPatch(ctx context.Context, tx DBTX, current *types.Issue, parent publicops.Field[string], actor string) (ParentPatchResult, error) {
if !parent.Set {
return ParentPatchResult{}, nil
}
dependencies, err := GetDependencyRecordsForIssuesInTx(ctx, tx, []string{current.ID})
if err != nil {
return ParentPatchResult{}, err
}
existing := map[string]struct{}{}
for _, dependency := range dependencies[current.ID] {
if dependency.Type == types.DepParentChild {
existing[dependency.DependsOnID] = struct{}{}
}
}
target := map[string]struct{}{}
if parent.Value != "" {
target[parent.Value] = struct{}{}
}
if sameStringSet(existing, target) {
return ParentPatchResult{}, nil
}
sqlTx, ok := tx.(*sql.Tx)
if !ok {
return ParentPatchResult{}, fmt.Errorf("apply parent: transaction must be *sql.Tx")
}
var recomputed RecomputeIsBlockedResult
for _, parentID := range stringSetDifference(existing, target) {
if _, err := removeDependencyInTx(ctx, sqlTx, current.ID, parentID, actor, false, &recomputed); err != nil {
return ParentPatchResult{}, err
}
}
for _, parentID := range stringSetDifference(target, existing) {
if _, err := addDependencyInTx(ctx, sqlTx, &types.Dependency{IssueID: current.ID, DependsOnID: parentID, Type: types.DepParentChild}, actor, AddDependencyOpts{}, &recomputed); err != nil {
return ParentPatchResult{}, err
}
}
return ParentPatchResult{Changed: true, IssueRowsChanged: recomputed.IssueRowsChanged, WispRowsChanged: recomputed.WispRowsChanged}, nil
}
func stringSet(values []string) map[string]struct{} {
set := make(map[string]struct{}, len(values))
for _, value := range values {
set[value] = struct{}{}
}
return set
}
func sameStringSet(left, right map[string]struct{}) bool {
if len(left) != len(right) {
return false
}
for value := range left {
if _, ok := right[value]; !ok {
return false
}
}
return true
}
func stringSetDifference(left, right map[string]struct{}) []string {
values := make([]string, 0)
for value := range left {
if _, ok := right[value]; !ok {
values = append(values, value)
}
}
sort.Strings(values)
return values
}