beads/internal/github/mapping.go
Kevin Glynn 9827c66319
fix(github): content-based dedup on push to stop re-PATCHing every issue (#4214) (#4329)
* fix(github): content-based dedup on push to stop re-PATCHing every issue

GitHub sync never wired engine.PushHooks, so `doPush` fell back to
timestamp-only dedup. Because linking and any local write bump a beads
issue's updated_at past GitHub's second-granularity updated_at, every
`github sync --push-only` / `github push` reconciled and PATCHed the
entire backlog on every run — O(N) REST calls that drain the shared
installation's primary rate limit even when nothing changed.

Add github.PushFieldsEqual, comparing only the fields a push mutates
(title, body, state, and the label set BeadsIssueToGitHubFields sends,
order-insensitive). Wire a ContentEqual push hook (buildGitHubPushHooks)
into both runGitHubSync and runGitHubPush so the engine skips issues
already in sync — mirroring the existing Linear/Jira push hooks.

Dry-run still makes 0 REST calls (unchanged); this targets the live
re-PATCH storm. A push-side incremental cursor to also avoid the
per-issue fetch is a noted follow-up.

Fixes #4214

Co-authored-by: Cursor <cursoragent@cursor.com>

* perf(sync): skip per-issue fetch on no-op push via persisted content hash

The ContentEqual hook added for #4214 stops the redundant PATCH but still
fetches every linked issue (one GET each), so a no-op `github sync --push-only`
still drains the REST rate limit. Add a ContentHash push hook: the engine
persists each issue's pushed content hash in the dolt-ignored local_metadata
table and consults it before FetchIssue. When the local content is unchanged
since the last push, the fetch and update are skipped entirely.

Also record the hash when ContentEqual reports a match (so the first
post-restart pass repopulates hashes) and consult it in dry-run, so an
unchanged issue previews as a skip instead of always reporting "Would update".

Refs gastownhall/beads#4214

Co-authored-by: Cursor <cursoragent@cursor.com>

* shrink(github): simplify PushContentHash framing and labelSetsEqual

Replace length-prefix binary framing in PushContentHash with NUL-separated
fields — the hash is only self-compared, so the simpler scheme is sufficient.
Replace hand-rolled counting map in labelSetsEqual with slices.Sort +
slices.Equal. Drop unused encoding/binary, strconv, sort imports in favor
of slices.

Agent-Signature: cursor-opus-4.6-unknown-reasoning on behalf of kevglynn
Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(sync): bind push cache to remote target

Agent-Signature: codex-gpt-5.6-sol-medium on behalf of matt wilkie

---------

Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: matt wilkie <maphew@gmail.com>
2026-08-02 22:53:06 -07:00

306 lines
8.9 KiB
Go

// Package github provides client and data types for the GitHub REST API.
package github
import (
"crypto/sha256"
"encoding/hex"
"fmt"
"slices"
"strings"
"github.com/steveyegge/beads/internal/types"
)
// MappingConfig configures how GitHub fields map to beads fields.
type MappingConfig struct {
PriorityMap map[string]int // priority label value -> beads priority (0-4)
StateMap map[string]string // GitHub state -> beads status
LabelTypeMap map[string]string // type label value -> beads issue type
}
// DefaultMappingConfig returns the default mapping configuration.
// Uses exported mapping constants from types.go as the single source of truth.
func DefaultMappingConfig() *MappingConfig {
// Copy PriorityMapping to avoid external modification
priorityMap := make(map[string]int, len(PriorityMapping))
for k, v := range PriorityMapping {
priorityMap[k] = v
}
// Copy typeMapping to avoid external modification
labelTypeMap := make(map[string]string, len(typeMapping))
for k, v := range typeMapping {
labelTypeMap[k] = v
}
return &MappingConfig{
PriorityMap: priorityMap,
// StateMap maps GitHub states to beads statuses
StateMap: map[string]string{
"open": StatusMapping["open"],
"closed": StatusMapping["closed"],
},
LabelTypeMap: labelTypeMap,
}
}
// priorityFromLabels extracts priority from GitHub labels.
// Returns default priority (2 = medium) if no priority label found.
func priorityFromLabels(labels []string, config *MappingConfig) int {
for _, label := range labels {
prefix, value := parseLabelPrefix(label)
if prefix == "priority" {
if p, ok := config.PriorityMap[strings.ToLower(value)]; ok {
return p
}
}
}
return 2 // Default to medium
}
// statusFromLabelsAndState determines beads status from GitHub labels and state.
// GitHub's closed state takes precedence over status labels.
func statusFromLabelsAndState(labels []string, state string, config *MappingConfig) string {
// Closed state always wins
if state == "closed" {
return "closed"
}
// Check for status label
for _, label := range labels {
prefix, value := parseLabelPrefix(label)
if prefix == "status" {
normalized := strings.ToLower(value)
if normalized == "in_progress" {
return "in_progress"
}
if normalized == "blocked" {
return "blocked"
}
if normalized == "deferred" {
return "deferred"
}
}
}
// Default: map GitHub state to beads status
if s, ok := config.StateMap[state]; ok {
return s
}
return "open"
}
// typeFromLabels extracts issue type from GitHub labels.
// Checks both scoped (type::bug) and bare (bug) labels.
// Returns "task" if no type label found.
func typeFromLabels(labels []string, config *MappingConfig) string {
for _, label := range labels {
prefix, value := parseLabelPrefix(label)
if prefix == "type" {
if t, ok := config.LabelTypeMap[strings.ToLower(value)]; ok {
return t
}
}
// Also check bare labels (no prefix)
if prefix == "" {
if t, ok := config.LabelTypeMap[strings.ToLower(value)]; ok {
return t
}
}
}
return "task" // Default to task
}
// GitHubIssueToBeads converts a GitHub Issue to a beads Issue.
func GitHubIssueToBeads(gh *Issue, config *MappingConfig) *IssueConversion {
htmlURL := gh.HTMLURL
sourceSystem := fmt.Sprintf("github:%s:%d", gh.HTMLURL, gh.Number)
// Use a cleaner source system format if HTMLURL is not available
if htmlURL == "" {
sourceSystem = fmt.Sprintf("github:%d:%d", gh.ID, gh.Number)
}
labelNames := gh.LabelNames()
issue := &types.Issue{
Title: gh.Title,
Description: gh.Body,
ExternalRef: &htmlURL,
SourceSystem: sourceSystem,
IssueType: types.IssueType(typeFromLabels(labelNames, config)),
Priority: priorityFromLabels(labelNames, config),
Status: types.Status(statusFromLabelsAndState(labelNames, gh.State, config)),
Labels: filterNonScopedLabels(labelNames),
}
// Set assignee from GitHub user
if gh.Assignee != nil {
issue.Assignee = gh.Assignee.Login
}
// Set timestamps
if gh.CreatedAt != nil {
issue.CreatedAt = *gh.CreatedAt
}
if gh.UpdatedAt != nil {
issue.UpdatedAt = *gh.UpdatedAt
}
return &IssueConversion{
Issue: issue,
Dependencies: []DependencyInfo{},
}
}
// BeadsIssueToGitHubFields converts a beads Issue to GitHub API update fields.
func BeadsIssueToGitHubFields(issue *types.Issue, config *MappingConfig) map[string]interface{} {
fields := map[string]interface{}{
"title": issue.Title,
"body": issue.Description,
}
// Build labels from type, priority, and status
var labels []string
// Add type label
if issue.IssueType != "" {
labels = append(labels, "type::"+string(issue.IssueType))
}
// Add priority label
priorityLabel := priorityToLabel(issue.Priority)
if priorityLabel != "" {
labels = append(labels, "priority::"+priorityLabel)
}
// Add status label (if not open or closed - those are handled by state)
if issue.Status == types.StatusInProgress {
labels = append(labels, "status::in_progress")
} else if issue.Status == types.StatusBlocked {
labels = append(labels, "status::blocked")
} else if issue.Status == types.StatusDeferred {
labels = append(labels, "status::deferred")
}
// Add any existing non-scoped labels
labels = append(labels, issue.Labels...)
fields["labels"] = labels
// Set state for closed issues
if issue.Status == types.StatusClosed {
fields["state"] = "closed"
} else {
fields["state"] = "open"
}
return fields
}
// PushFieldsEqual reports whether a GitHub push would be a no-op by comparing
// only the fields a push can actually mutate: title, body, state, and the
// label set that BeadsIssueToGitHubFields would send. When these already match
// the remote issue, the push is redundant and can be skipped — this is what
// prevents `bd github sync --push-only` from re-PATCHing every issue on every
// run (gastownhall/beads#4214). Mirrors linear.PushFieldsEqual.
func PushFieldsEqual(local *types.Issue, remote *Issue, config *MappingConfig) bool {
if local == nil || remote == nil {
return false
}
if local.Title != remote.Title {
return false
}
if local.Description != remote.Body {
return false
}
desiredState := "open"
if local.Status == types.StatusClosed {
desiredState = "closed"
}
if !strings.EqualFold(desiredState, remote.State) {
return false
}
// Compare the label set we would push against the remote's current labels.
// Both include the scoped type::/priority::/status:: labels plus any
// non-scoped labels, so an unchanged issue produces an identical set.
desiredLabels, _ := BeadsIssueToGitHubFields(local, config)["labels"].([]string)
return labelSetsEqual(desiredLabels, remote.LabelNames())
}
// PushContentHash returns a stable hex fingerprint of the fields a push would
// send to GitHub: title, body, desired state, and the order-independent label
// set produced by BeadsIssueToGitHubFields. The engine persists this hash in
// local_metadata after each push and compares it before fetching the remote
// issue, so an unchanged issue is skipped without any API call
// (gastownhall/beads#4214). It is derived from the same fields PushFieldsEqual
// compares, so the two agree on what "unchanged" means. Fields are
// length-prefixed before hashing so distinct field boundaries cannot collide.
func PushContentHash(local *types.Issue, config *MappingConfig) string {
if local == nil {
return ""
}
desiredState := "open"
if local.Status == types.StatusClosed {
desiredState = "closed"
}
desiredLabels, _ := BeadsIssueToGitHubFields(local, config)["labels"].([]string)
sortedLabels := append([]string(nil), desiredLabels...)
slices.Sort(sortedLabels)
h := sha256.New()
for _, s := range []string{local.Title, local.Description, desiredState, strings.Join(sortedLabels, "\x00")} {
_, _ = h.Write([]byte(s))
_, _ = h.Write([]byte{0})
}
return hex.EncodeToString(h.Sum(nil))
}
// labelSetsEqual reports whether a and b contain the same labels, ignoring
// order (GitHub does not preserve label order across a round-trip).
func labelSetsEqual(a, b []string) bool {
if len(a) != len(b) {
return false
}
as := append([]string(nil), a...)
bs := append([]string(nil), b...)
slices.Sort(as)
slices.Sort(bs)
return slices.Equal(as, bs)
}
// priorityToLabel converts beads priority (0-4) to GitHub priority label value.
func priorityToLabel(priority int) string {
switch priority {
case 0:
return "critical"
case 1:
return "high"
case 2:
return "medium"
case 3:
return "low"
case 4:
return "none"
default:
return "medium"
}
}
// filterNonScopedLabels returns only labels without scoped prefixes.
// Removes priority::*, status::*, and type::* labels.
func filterNonScopedLabels(labels []string) []string {
var filtered []string
for _, label := range labels {
prefix, _ := parseLabelPrefix(label)
// Skip scoped labels that we handle specially
if prefix == "priority" || prefix == "status" || prefix == "type" {
continue
}
filtered = append(filtered, label)
}
return filtered
}