`5cbcc45`

S21: issues orchestrator (create/comment/state/lock + labels/milestones/refs) + tests

Authored by mfwolffe <wolffemf@dukes.jmu.edu> 6 days ago

SHA: 5cbcc452109ad6b41c74294ea8e0cea08f9d63d1
Parents: a396715
Tree: 6cff6f5

6 changed files

Status	File	+
A	`internal/issues/issues.go`	312
A	`internal/issues/issues_test.go`	263
A	`internal/issues/labels.go`	204
A	`internal/issues/milestones.go`	196
A	`internal/issues/references.go`	165
A	`internal/issues/references_test.go`	83

internal/issues/issues.goadded

++// SPDX-License-Identifier: AGPL-3.0-or-later
++
++// Package issues owns the issue + comment + label + milestone domain
++// logic. Web handlers call into this package; the package owns
++// transactions, cross-reference parsing, and event emission.
++//
++// PR-specific behavior lives in the future internal/pulls/ package
++// (S22) — but PRs reuse the `issues` and `issue_comments` tables, so
++// the queries here are kind-discriminated to keep the surface clean.
++package issues
++
++import (
++	"context"
++	"errors"
++	"fmt"
++	"log/slog"
++	"strings"
++	"time"
++
++	"github.com/jackc/pgx/v5"
++	"github.com/jackc/pgx/v5/pgtype"
++	"github.com/jackc/pgx/v5/pgxpool"
++
++	"github.com/tenseleyFlow/shithub/internal/auth/throttle"
++	issuesdb "github.com/tenseleyFlow/shithub/internal/issues/sqlc"
++	mdrender "github.com/tenseleyFlow/shithub/internal/repos/markdown"
++)
++
++// Deps wires this package against the rest of the runtime. Pool is
++// required; Limiter governs the comment-create rate limit; Logger is
++// optional (falls back to discarding when nil).
++type Deps struct {
++	Pool    *pgxpool.Pool
++	Limiter *throttle.Limiter
++	Logger  *slog.Logger
++}
++
++// Errors returned by the orchestrator. Handlers map these to status
++// codes + friendly user-facing messages.
++var (
++	ErrEmptyTitle        = errors.New("issues: title is required")
++	ErrTitleTooLong      = errors.New("issues: title too long (max 256)")
++	ErrBodyTooLong       = errors.New("issues: body too long")
++	ErrCommentTooLong    = errors.New("issues: comment too long")
++	ErrIssueLocked       = errors.New("issues: issue is locked")
++	ErrCommentRateLimit  = errors.New("issues: comment rate limit exceeded")
++	ErrLabelExists       = errors.New("issues: label name already taken on this repo")
++	ErrLabelInvalidColor = errors.New("issues: label color must be 6 hex chars")
++	ErrMilestoneExists   = errors.New("issues: milestone title already taken on this repo")
++	ErrIssueNotFound     = errors.New("issues: issue not found")
++)
++
++// CreateParams describes a new-issue request.
++type CreateParams struct {
++	RepoID       int64
++	AuthorUserID int64 // 0 means anonymous (unsupported in S21; handler enforces)
++	Title        string
++	Body         string
++	// Kind defaults to "issue"; PR creation in S22 passes "pr".
++	Kind string
++}
++
++// Create validates inputs, allocates a per-repo number atomically,
++// inserts the row, renders the body's markdown, and returns the
++// fresh issue. Default labels live with repo create; per-issue
++// label/assignee/milestone application is a separate call.
++//
++// Cross-reference indexing fires asynchronously inside the same tx
++// via insertReferencesFromBody — refs to other issues create
++// `issue_references` rows + a `referenced` event on the target.
++func Create(ctx context.Context, deps Deps, p CreateParams) (issuesdb.Issue, error) {
++	title := strings.TrimSpace(p.Title)
++	if title == "" {
++		return issuesdb.Issue{}, ErrEmptyTitle
++	}
++	if len(title) > 256 {
++		return issuesdb.Issue{}, ErrTitleTooLong
++	}
++	if len(p.Body) > 65535 {
++		return issuesdb.Issue{}, ErrBodyTooLong
++	}
++	kind := p.Kind
++	if kind == "" {
++		kind = "issue"
++	}
++
++	tx, err := deps.Pool.Begin(ctx)
++	if err != nil {
++		return issuesdb.Issue{}, fmt.Errorf("begin: %w", err)
++	}
++	committed := false
++	defer func() {
++		if !committed {
++			_ = tx.Rollback(ctx)
++		}
++	}()
++
++	q := issuesdb.New()
++	if err := q.EnsureRepoIssueCounter(ctx, tx, p.RepoID); err != nil {
++		return issuesdb.Issue{}, fmt.Errorf("counter init: %w", err)
++	}
++	num, err := q.AllocateIssueNumber(ctx, tx, p.RepoID)
++	if err != nil {
++		return issuesdb.Issue{}, fmt.Errorf("allocate number: %w", err)
++	}
++
++	row, err := q.CreateIssue(ctx, tx, issuesdb.CreateIssueParams{
++		RepoID:       p.RepoID,
++		Number:       num,
++		Kind:         issuesdb.IssueKind(kind),
++		Title:        title,
++		Body:         p.Body,
++		AuthorUserID: pgtype.Int8{Int64: p.AuthorUserID, Valid: p.AuthorUserID != 0},
++	})
++	if err != nil {
++		return issuesdb.Issue{}, fmt.Errorf("insert: %w", err)
++	}
++
++	// Render markdown for the cached body html.
++	html, _ := mdrender.RenderHTML([]byte(p.Body))
++	row.BodyHtmlCached = pgtype.Text{String: html, Valid: html != ""}
++
++	if err := q.UpdateIssueTitleBody(ctx, tx, issuesdb.UpdateIssueTitleBodyParams{
++		ID: row.ID, Title: row.Title, Body: row.Body,
++		BodyHtmlCached: pgtype.Text{String: html, Valid: html != ""},
++	}); err != nil {
++		return issuesdb.Issue{}, fmt.Errorf("update html: %w", err)
++	}
++
++	if err := insertReferencesFromBody(ctx, tx, deps, row, p.Body, "issue_body", row.ID); err != nil {
++		return issuesdb.Issue{}, fmt.Errorf("refs: %w", err)
++	}
++
++	if err := tx.Commit(ctx); err != nil {
++		return issuesdb.Issue{}, fmt.Errorf("commit: %w", err)
++	}
++	committed = true
++	return row, nil
++}
++
++// CommentCreateParams is the input for AddComment.
++type CommentCreateParams struct {
++	IssueID      int64
++	AuthorUserID int64
++	Body         string
++	// IsCollab signals that the actor's policy.Can role is at least
++	// triage. Used to bypass the locked-issue gate.
++	IsCollab bool
++}
++
++// AddComment validates, applies the rate limit, inserts the comment,
++// and indexes references. Returns the fresh comment.
++func AddComment(ctx context.Context, deps Deps, p CommentCreateParams) (issuesdb.IssueComment, error) {
++	body := strings.TrimSpace(p.Body)
++	if body == "" || len(body) > 65535 {
++		return issuesdb.IssueComment{}, ErrCommentTooLong
++	}
++	if deps.Limiter != nil && p.AuthorUserID != 0 {
++		if err := deps.Limiter.Hit(ctx, deps.Pool, throttle.Limit{
++			Scope:      "issue_comment",
++			Identifier: fmt.Sprintf("user:%d", p.AuthorUserID),
++			Max:        20,
++			Window:     time.Hour,
++		}); err != nil {
++			return issuesdb.IssueComment{}, ErrCommentRateLimit
++		}
++	}
++
++	q := issuesdb.New()
++	issue, err := q.GetIssueByID(ctx, deps.Pool, p.IssueID)
++	if err != nil {
++		if errors.Is(err, pgx.ErrNoRows) {
++			return issuesdb.IssueComment{}, ErrIssueNotFound
++		}
++		return issuesdb.IssueComment{}, err
++	}
++	if issue.Locked && !p.IsCollab {
++		return issuesdb.IssueComment{}, ErrIssueLocked
++	}
++
++	html, _ := mdrender.RenderHTML([]byte(body))
++
++	tx, err := deps.Pool.Begin(ctx)
++	if err != nil {
++		return issuesdb.IssueComment{}, err
++	}
++	committed := false
++	defer func() {
++		if !committed {
++			_ = tx.Rollback(ctx)
++		}
++	}()
++
++	c, err := q.CreateIssueComment(ctx, tx, issuesdb.CreateIssueCommentParams{
++		IssueID:        p.IssueID,
++		AuthorUserID:   pgtype.Int8{Int64: p.AuthorUserID, Valid: p.AuthorUserID != 0},
++		Body:           body,
++		BodyHtmlCached: pgtype.Text{String: html, Valid: html != ""},
++	})
++	if err != nil {
++		return issuesdb.IssueComment{}, err
++	}
++
++	if err := insertReferencesFromBody(ctx, tx, deps, issue, body, "comment_body", c.ID); err != nil {
++		return issuesdb.IssueComment{}, err
++	}
++
++	if err := tx.Commit(ctx); err != nil {
++		return issuesdb.IssueComment{}, err
++	}
++	committed = true
++	return c, nil
++}
++
++// SetState closes or reopens an issue and emits an `closed` /
++// `reopened` event.
++func SetState(ctx context.Context, deps Deps, actorUserID, issueID int64, newState, reason string) error {
++	if newState != "open" && newState != "closed" {
++		return errors.New("issues: state must be open or closed")
++	}
++	tx, err := deps.Pool.Begin(ctx)
++	if err != nil {
++		return err
++	}
++	committed := false
++	defer func() {
++		if !committed {
++			_ = tx.Rollback(ctx)
++		}
++	}()
++
++	q := issuesdb.New()
++	closedBy := pgtype.Int8{}
++	if newState == "closed" && actorUserID != 0 {
++		closedBy = pgtype.Int8{Int64: actorUserID, Valid: true}
++	}
++	stateReason := pgtype.Text{}
++	if reason != "" {
++		stateReason = pgtype.Text{String: reason, Valid: true}
++	}
++	if err := q.SetIssueState(ctx, tx, issuesdb.SetIssueStateParams{
++		ID:             issueID,
++		State:          issuesdb.IssueState(newState),
++		StateReason:    issuesdb.NullIssueStateReason{IssueStateReason: issuesdb.IssueStateReason(stateReason.String), Valid: stateReason.Valid},
++		ClosedByUserID: closedBy,
++	}); err != nil {
++		return err
++	}
++	kind := "closed"
++	if newState == "open" {
++		kind = "reopened"
++	}
++	if _, err := q.InsertIssueEvent(ctx, tx, issuesdb.InsertIssueEventParams{
++		IssueID:     issueID,
++		ActorUserID: pgtype.Int8{Int64: actorUserID, Valid: actorUserID != 0},
++		Kind:        kind,
++		Meta:        emptyMeta,
++	}); err != nil {
++		return err
++	}
++	if err := tx.Commit(ctx); err != nil {
++		return err
++	}
++	committed = true
++	return nil
++}
++
++// emptyMeta is the JSON object passed when an event carries no metadata.
++// The column is NOT NULL DEFAULT '{}'::jsonb, but binding nil from Go
++// sends SQL NULL rather than letting the DEFAULT fire — so callers
++// pass this explicitly.
++var emptyMeta = []byte("{}")
++
++// SetLock toggles the locked flag and emits an event.
++func SetLock(ctx context.Context, deps Deps, actorUserID, issueID int64, locked bool, reason string) error {
++	q := issuesdb.New()
++	tx, err := deps.Pool.Begin(ctx)
++	if err != nil {
++		return err
++	}
++	committed := false
++	defer func() {
++		if !committed {
++			_ = tx.Rollback(ctx)
++		}
++	}()
++	rsn := pgtype.Text{}
++	if reason != "" {
++		rsn = pgtype.Text{String: reason, Valid: true}
++	}
++	if err := q.SetIssueLock(ctx, tx, issuesdb.SetIssueLockParams{
++		ID: issueID, Locked: locked, LockReason: rsn,
++	}); err != nil {
++		return err
++	}
++	kind := "locked"
++	if !locked {
++		kind = "unlocked"
++	}
++	if _, err := q.InsertIssueEvent(ctx, tx, issuesdb.InsertIssueEventParams{
++		IssueID: issueID, ActorUserID: pgtype.Int8{Int64: actorUserID, Valid: actorUserID != 0},
++		Kind: kind,
++		Meta: emptyMeta,
++	}); err != nil {
++		return err
++	}
++	if err := tx.Commit(ctx); err != nil {
++		return err
++	}
++	committed = true
++	return nil
++}

internal/issues/issues_test.goadded

++// SPDX-License-Identifier: AGPL-3.0-or-later
++
++package issues_test
++
++import (
++	"context"
++	"io"
++	"log/slog"
++	"strings"
++	"sync"
++	"testing"
++
++	"github.com/jackc/pgx/v5/pgtype"
++	"github.com/jackc/pgx/v5/pgxpool"
++
++	"github.com/tenseleyFlow/shithub/internal/auth/throttle"
++	"github.com/tenseleyFlow/shithub/internal/issues"
++	issuesdb "github.com/tenseleyFlow/shithub/internal/issues/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"
++
++// setup spins a fresh test DB, creates a user + repo, seeds the issue
++// counter, and returns the things the issue tests need.
++func setup(t *testing.T) (*pgxpool.Pool, issues.Deps, int64, int64) {
++	t.Helper()
++	pool := dbtest.NewTestDB(t)
++	ctx := context.Background()
++
++	uq := usersdb.New()
++	user, err := uq.CreateUser(ctx, pool, usersdb.CreateUserParams{
++		Username: "alice", DisplayName: "Alice", PasswordHash: fixtureHash,
++	})
++	if err != nil {
++		t.Fatalf("CreateUser: %v", err)
++	}
++
++	rq := reposdb.New()
++	repo, err := rq.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)
++	}
++	iq := issuesdb.New()
++	if err := iq.EnsureRepoIssueCounter(ctx, pool, repo.ID); err != nil {
++		t.Fatalf("EnsureRepoIssueCounter: %v", err)
++	}
++
++	deps := issues.Deps{
++		Pool:    pool,
++		Limiter: throttle.NewLimiter(),
++		Logger:  slog.New(slog.NewTextHandler(io.Discard, nil)),
++	}
++	return pool, deps, user.ID, repo.ID
++}
++
++func TestCreate_AllocatesSequentialNumbers(t *testing.T) {
++	_, deps, uid, rid := setup(t)
++	ctx := context.Background()
++	for i := int64(1); i <= 3; i++ {
++		got, err := issues.Create(ctx, deps, issues.CreateParams{
++			RepoID: rid, AuthorUserID: uid, Title: "title", Body: "body",
++		})
++		if err != nil {
++			t.Fatalf("Create #%d: %v", i, err)
++		}
++		if got.Number != i {
++			t.Errorf("issue %d: got number %d, want %d", i, got.Number, i)
++		}
++	}
++}
++
++func TestCreate_ConcurrentRaceForUniqueNumbers(t *testing.T) {
++	_, deps, uid, rid := setup(t)
++	ctx := context.Background()
++	const N = 8
++	got := make([]int64, N)
++	var wg sync.WaitGroup
++	wg.Add(N)
++	for i := 0; i < N; i++ {
++		go func(i int) {
++			defer wg.Done()
++			row, err := issues.Create(ctx, deps, issues.CreateParams{
++				RepoID: rid, AuthorUserID: uid, Title: "race", Body: "body",
++			})
++			if err != nil {
++				t.Errorf("create %d: %v", i, err)
++				return
++			}
++			got[i] = row.Number
++		}(i)
++	}
++	wg.Wait()
++	seen := map[int64]bool{}
++	for _, n := range got {
++		if seen[n] {
++			t.Errorf("duplicate number %d in %v", n, got)
++		}
++		seen[n] = true
++		if n < 1 || n > N {
++			t.Errorf("number %d out of [1,%d] range", n, N)
++		}
++	}
++}
++
++func TestCreate_RejectsEmptyTitle(t *testing.T) {
++	_, deps, uid, rid := setup(t)
++	ctx := context.Background()
++	_, err := issues.Create(ctx, deps, issues.CreateParams{
++		RepoID: rid, AuthorUserID: uid, Title: "   ", Body: "body",
++	})
++	if err == nil || err.Error() == "" {
++		t.Fatalf("expected ErrEmptyTitle, got %v", err)
++	}
++}
++
++func TestCreate_RendersHTMLAndSanitizesScripts(t *testing.T) {
++	pool, deps, uid, rid := setup(t)
++	ctx := context.Background()
++	row, err := issues.Create(ctx, deps, issues.CreateParams{
++		RepoID:       rid,
++		AuthorUserID: uid,
++		Title:        "xss",
++		Body:         `before <script>alert("xss")</script> after **bold**`,
++	})
++	if err != nil {
++		t.Fatalf("Create: %v", err)
++	}
++	iq := issuesdb.New()
++	got, err := iq.GetIssueByID(ctx, pool, row.ID)
++	if err != nil {
++		t.Fatalf("GetIssueByID: %v", err)
++	}
++	if !got.BodyHtmlCached.Valid {
++		t.Fatalf("expected cached body html")
++	}
++	html := got.BodyHtmlCached.String
++	if strings.Contains(strings.ToLower(html), "<script") {
++		t.Errorf("sanitized html should not contain <script>: %q", html)
++	}
++	if !strings.Contains(html, "<strong>") {
++		t.Errorf("markdown should render bold: %q", html)
++	}
++}
++
++func TestAddComment_LockedRejectsNonCollab(t *testing.T) {
++	pool, deps, uid, rid := setup(t)
++	ctx := context.Background()
++	row, err := issues.Create(ctx, deps, issues.CreateParams{
++		RepoID: rid, AuthorUserID: uid, Title: "lock-me", Body: "",
++	})
++	if err != nil {
++		t.Fatalf("Create: %v", err)
++	}
++	if err := issues.SetLock(ctx, deps, uid, row.ID, true, "spam"); err != nil {
++		t.Fatalf("SetLock: %v", err)
++	}
++	uq := usersdb.New()
++	other, err := uq.CreateUser(ctx, pool, usersdb.CreateUserParams{
++		Username: "carol", DisplayName: "Carol", PasswordHash: fixtureHash,
++	})
++	if err != nil {
++		t.Fatalf("CreateUser: %v", err)
++	}
++	_, err = issues.AddComment(ctx, deps, issues.CommentCreateParams{
++		IssueID:      row.ID,
++		AuthorUserID: other.ID,
++		Body:         "let me in",
++		IsCollab:     false,
++	})
++	if err == nil {
++		t.Fatalf("expected ErrIssueLocked, got nil")
++	}
++}
++
++func TestSetState_EmitsEvent(t *testing.T) {
++	pool, deps, uid, rid := setup(t)
++	ctx := context.Background()
++	row, err := issues.Create(ctx, deps, issues.CreateParams{
++		RepoID: rid, AuthorUserID: uid, Title: "close-me", Body: "",
++	})
++	if err != nil {
++		t.Fatalf("Create: %v", err)
++	}
++	if err := issues.SetState(ctx, deps, uid, row.ID, "closed", "completed"); err != nil {
++		t.Fatalf("SetState: %v", err)
++	}
++	if err := issues.SetState(ctx, deps, uid, row.ID, "open", ""); err != nil {
++		t.Fatalf("SetState reopen: %v", err)
++	}
++	iq := issuesdb.New()
++	events, err := iq.ListIssueEvents(ctx, pool, row.ID)
++	if err != nil {
++		t.Fatalf("ListIssueEvents: %v", err)
++	}
++	kinds := []string{}
++	for _, e := range events {
++		kinds = append(kinds, e.Kind)
++	}
++	want := []string{"closed", "reopened"}
++	if len(kinds) != 2 || kinds[0] != want[0] || kinds[1] != want[1] {
++		t.Errorf("got events %v, want %v", kinds, want)
++	}
++}
++
++func TestCreate_CrossReferenceCreatesEventOnTarget(t *testing.T) {
++	pool, deps, uid, rid := setup(t)
++	ctx := context.Background()
++	first, err := issues.Create(ctx, deps, issues.CreateParams{
++		RepoID: rid, AuthorUserID: uid, Title: "first", Body: "no refs",
++	})
++	if err != nil {
++		t.Fatalf("Create first: %v", err)
++	}
++	if _, err := issues.Create(ctx, deps, issues.CreateParams{
++		RepoID: rid, AuthorUserID: uid, Title: "second", Body: "fixes #" + itoa(first.Number),
++	}); err != nil {
++		t.Fatalf("Create second: %v", err)
++	}
++	iq := issuesdb.New()
++	events, err := iq.ListIssueEvents(ctx, pool, first.ID)
++	if err != nil {
++		t.Fatalf("ListIssueEvents: %v", err)
++	}
++	found := false
++	for _, e := range events {
++		if e.Kind == "referenced" {
++			found = true
++		}
++	}
++	if !found {
++		t.Errorf("expected `referenced` event on target issue, got %#v", events)
++	}
++}
++
++// itoa minimizes deps in tests.
++func itoa(v int64) string {
++	if v == 0 {
++		return "0"
++	}
++	out := make([]byte, 0, 4)
++	neg := v < 0
++	if neg {
++		v = -v
++	}
++	for v > 0 {
++		out = append([]byte{byte('0' + v%10)}, out...)
++		v /= 10
++	}
++	if neg {
++		out = append([]byte{'-'}, out...)
++	}
++	return string(out)
++}

internal/issues/labels.goadded

++// SPDX-License-Identifier: AGPL-3.0-or-later
++
++package issues
++
++import (
++	"context"
++	"errors"
++	"regexp"
++	"strconv"
++	"strings"
++
++	"github.com/jackc/pgx/v5/pgconn"
++	"github.com/jackc/pgx/v5/pgtype"
++
++	issuesdb "github.com/tenseleyFlow/shithub/internal/issues/sqlc"
++)
++
++// DefaultLabels is the seeded set applied to every new repo. Names +
++// colors are GitHub-aligned so users feel at home.
++var DefaultLabels = []LabelSeed{
++	{"bug", "d73a4a", "Something isn't working"},
++	{"documentation", "0075ca", "Improvements or additions to documentation"},
++	{"duplicate", "cfd3d7", "This issue or pull request already exists"},
++	{"enhancement", "a2eeef", "New feature or request"},
++	{"good first issue", "7057ff", "Good for newcomers"},
++	{"help wanted", "008672", "Extra attention is needed"},
++	{"invalid", "e4e669", "This doesn't seem right"},
++	{"question", "d876e3", "Further information is requested"},
++	{"wontfix", "ffffff", "This will not be worked on"},
++}
++
++type LabelSeed struct{ Name, Color, Description string }
++
++var reHexColor = regexp.MustCompile(`^[0-9a-fA-F]{6}$`)
++
++// LabelCreateParams is input for CreateLabel.
++type LabelCreateParams struct {
++	RepoID      int64
++	Name        string
++	Color       string
++	Description string
++}
++
++// CreateLabel validates and inserts a label. Color must be 6 hex chars.
++func CreateLabel(ctx context.Context, deps Deps, p LabelCreateParams) (issuesdb.Label, error) {
++	name := strings.TrimSpace(p.Name)
++	if name == "" || len(name) > 50 {
++		return issuesdb.Label{}, errors.New("issues: label name length 1–50")
++	}
++	color := normalizeColor(p.Color)
++	if !reHexColor.MatchString(color) {
++		return issuesdb.Label{}, ErrLabelInvalidColor
++	}
++	q := issuesdb.New()
++	row, err := q.CreateLabel(ctx, deps.Pool, issuesdb.CreateLabelParams{
++		RepoID:      p.RepoID,
++		Name:        name,
++		Color:       strings.ToLower(color),
++		Description: p.Description,
++	})
++	if err != nil {
++		if isUniqueViolation(err) {
++			return issuesdb.Label{}, ErrLabelExists
++		}
++		return issuesdb.Label{}, err
++	}
++	return row, nil
++}
++
++// SeedDefaultLabels writes the DefaultLabels into the given repo on
++// the supplied DBTX (typically the repo-create transaction). Existing
++// rows are left alone — caller can re-run safely.
++func SeedDefaultLabels(ctx context.Context, db issuesdb.DBTX, repoID int64) error {
++	q := issuesdb.New()
++	for _, l := range DefaultLabels {
++		_, err := q.CreateLabel(ctx, db, issuesdb.CreateLabelParams{
++			RepoID:      repoID,
++			Name:        l.Name,
++			Color:       l.Color,
++			Description: l.Description,
++		})
++		if err != nil && !isUniqueViolation(err) {
++			return err
++		}
++	}
++	return nil
++}
++
++// LabelUpdateParams is input for UpdateLabel.
++type LabelUpdateParams struct {
++	ID          int64
++	Name        string
++	Color       string
++	Description string
++}
++
++func UpdateLabel(ctx context.Context, deps Deps, p LabelUpdateParams) error {
++	name := strings.TrimSpace(p.Name)
++	if name == "" || len(name) > 50 {
++		return errors.New("issues: label name length 1–50")
++	}
++	color := normalizeColor(p.Color)
++	if !reHexColor.MatchString(color) {
++		return ErrLabelInvalidColor
++	}
++	q := issuesdb.New()
++	if err := q.UpdateLabel(ctx, deps.Pool, issuesdb.UpdateLabelParams{
++		ID:          p.ID,
++		Name:        name,
++		Color:       strings.ToLower(color),
++		Description: p.Description,
++	}); err != nil {
++		if isUniqueViolation(err) {
++			return ErrLabelExists
++		}
++		return err
++	}
++	return nil
++}
++
++// DeleteLabel removes a label.
++func DeleteLabel(ctx context.Context, deps Deps, id int64) error {
++	q := issuesdb.New()
++	return q.DeleteLabel(ctx, deps.Pool, id)
++}
++
++// ApplyLabels replaces the issue's label set with `labelIDs`. Emits a
++// `labeled` / `unlabeled` event for each delta. Caller is the actor.
++func ApplyLabels(ctx context.Context, deps Deps, actorUserID, issueID int64, labelIDs []int64) error {
++	q := issuesdb.New()
++	tx, err := deps.Pool.Begin(ctx)
++	if err != nil {
++		return err
++	}
++	committed := false
++	defer func() {
++		if !committed {
++			_ = tx.Rollback(ctx)
++		}
++	}()
++	current, err := q.ListLabelsOnIssue(ctx, tx, issueID)
++	if err != nil {
++		return err
++	}
++	want := map[int64]struct{}{}
++	for _, id := range labelIDs {
++		want[id] = struct{}{}
++	}
++	have := map[int64]struct{}{}
++	for _, l := range current {
++		have[l.ID] = struct{}{}
++	}
++	actor := pgtype.Int8{Int64: actorUserID, Valid: actorUserID != 0}
++	for id := range want {
++		if _, ok := have[id]; ok {
++			continue
++		}
++		if err := q.AddIssueLabel(ctx, tx, issuesdb.AddIssueLabelParams{
++			IssueID: issueID, LabelID: id, AppliedByUserID: actor,
++		}); err != nil {
++			return err
++		}
++		if _, err := q.InsertIssueEvent(ctx, tx, issuesdb.InsertIssueEventParams{
++			IssueID: issueID, ActorUserID: actor, Kind: "labeled",
++			Meta: []byte(`{"label_id":` + strconv.FormatInt(id, 10) + `}`),
++		}); err != nil {
++			return err
++		}
++	}
++	for id := range have {
++		if _, ok := want[id]; ok {
++			continue
++		}
++		if err := q.RemoveIssueLabel(ctx, tx, issuesdb.RemoveIssueLabelParams{
++			IssueID: issueID, LabelID: id,
++		}); err != nil {
++			return err
++		}
++		if _, err := q.InsertIssueEvent(ctx, tx, issuesdb.InsertIssueEventParams{
++			IssueID: issueID, ActorUserID: actor, Kind: "unlabeled",
++			Meta: []byte(`{"label_id":` + strconv.FormatInt(id, 10) + `}`),
++		}); err != nil {
++			return err
++		}
++	}
++	if err := tx.Commit(ctx); err != nil {
++		return err
++	}
++	committed = true
++	return nil
++}
++
++func normalizeColor(c string) string {
++	return strings.TrimPrefix(strings.TrimSpace(c), "#")
++}
++
++// isUniqueViolation maps Postgres SQLSTATE 23505 (unique_violation).
++func isUniqueViolation(err error) bool {
++	var pgErr *pgconn.PgError
++	if errors.As(err, &pgErr) {
++		return pgErr.Code == "23505"
++	}
++	return false
++}

internal/issues/milestones.goadded

++// SPDX-License-Identifier: AGPL-3.0-or-later
++
++package issues
++
++import (
++	"context"
++	"errors"
++	"strconv"
++	"strings"
++	"time"
++
++	"github.com/jackc/pgx/v5/pgtype"
++
++	issuesdb "github.com/tenseleyFlow/shithub/internal/issues/sqlc"
++)
++
++// MilestoneCreateParams is input for CreateMilestone.
++type MilestoneCreateParams struct {
++	RepoID      int64
++	Title       string
++	Description string
++	DueOn       *time.Time
++}
++
++func CreateMilestone(ctx context.Context, deps Deps, p MilestoneCreateParams) (issuesdb.Milestone, error) {
++	title := strings.TrimSpace(p.Title)
++	if title == "" || len(title) > 200 {
++		return issuesdb.Milestone{}, errors.New("issues: milestone title length 1–200")
++	}
++	due := pgtype.Timestamptz{}
++	if p.DueOn != nil {
++		due = pgtype.Timestamptz{Time: *p.DueOn, Valid: true}
++	}
++	q := issuesdb.New()
++	row, err := q.CreateMilestone(ctx, deps.Pool, issuesdb.CreateMilestoneParams{
++		RepoID: p.RepoID, Title: title, Description: p.Description, DueOn: due,
++	})
++	if err != nil {
++		if isUniqueViolation(err) {
++			return issuesdb.Milestone{}, ErrMilestoneExists
++		}
++		return issuesdb.Milestone{}, err
++	}
++	return row, nil
++}
++
++type MilestoneUpdateParams struct {
++	ID          int64
++	Title       string
++	Description string
++	DueOn       *time.Time
++}
++
++func UpdateMilestone(ctx context.Context, deps Deps, p MilestoneUpdateParams) error {
++	title := strings.TrimSpace(p.Title)
++	if title == "" || len(title) > 200 {
++		return errors.New("issues: milestone title length 1–200")
++	}
++	due := pgtype.Timestamptz{}
++	if p.DueOn != nil {
++		due = pgtype.Timestamptz{Time: *p.DueOn, Valid: true}
++	}
++	q := issuesdb.New()
++	if err := q.UpdateMilestone(ctx, deps.Pool, issuesdb.UpdateMilestoneParams{
++		ID: p.ID, Title: title, Description: p.Description, DueOn: due,
++	}); err != nil {
++		if isUniqueViolation(err) {
++			return ErrMilestoneExists
++		}
++		return err
++	}
++	return nil
++}
++
++func SetMilestoneState(ctx context.Context, deps Deps, id int64, state string) error {
++	if state != "open" && state != "closed" {
++		return errors.New("issues: milestone state must be open or closed")
++	}
++	q := issuesdb.New()
++	return q.SetMilestoneState(ctx, deps.Pool, issuesdb.SetMilestoneStateParams{
++		ID: id, State: issuesdb.MilestoneState(state),
++	})
++}
++
++func DeleteMilestone(ctx context.Context, deps Deps, id int64) error {
++	q := issuesdb.New()
++	return q.DeleteMilestone(ctx, deps.Pool, id)
++}
++
++// AssignMilestone sets an issue's milestone (or clears with milestoneID==0)
++// and emits a `milestoned`/`demilestoned` event.
++func AssignMilestone(ctx context.Context, deps Deps, actorUserID, issueID, milestoneID int64) error {
++	q := issuesdb.New()
++	tx, err := deps.Pool.Begin(ctx)
++	if err != nil {
++		return err
++	}
++	committed := false
++	defer func() {
++		if !committed {
++			_ = tx.Rollback(ctx)
++		}
++	}()
++	mid := pgtype.Int8{Int64: milestoneID, Valid: milestoneID != 0}
++	if err := q.SetIssueMilestone(ctx, tx, issuesdb.SetIssueMilestoneParams{
++		ID: issueID, MilestoneID: mid,
++	}); err != nil {
++		return err
++	}
++	kind := "milestoned"
++	mval := strconv.FormatInt(milestoneID, 10)
++	if milestoneID == 0 {
++		kind = "demilestoned"
++		mval = "null"
++	}
++	if _, err := q.InsertIssueEvent(ctx, tx, issuesdb.InsertIssueEventParams{
++		IssueID:     issueID,
++		ActorUserID: pgtype.Int8{Int64: actorUserID, Valid: actorUserID != 0},
++		Kind:        kind,
++		Meta:        []byte(`{"milestone_id":` + mval + `}`),
++	}); err != nil {
++		return err
++	}
++	if err := tx.Commit(ctx); err != nil {
++		return err
++	}
++	committed = true
++	return nil
++}
++
++// AssignUser adds an assignee + emits an `assigned` event.
++func AssignUser(ctx context.Context, deps Deps, actorUserID, issueID, userID int64) error {
++	q := issuesdb.New()
++	tx, err := deps.Pool.Begin(ctx)
++	if err != nil {
++		return err
++	}
++	committed := false
++	defer func() {
++		if !committed {
++			_ = tx.Rollback(ctx)
++		}
++	}()
++	if err := q.AssignUserToIssue(ctx, tx, issuesdb.AssignUserToIssueParams{
++		IssueID: issueID, UserID: userID,
++		AssignedByUserID: pgtype.Int8{Int64: actorUserID, Valid: actorUserID != 0},
++	}); err != nil {
++		return err
++	}
++	if _, err := q.InsertIssueEvent(ctx, tx, issuesdb.InsertIssueEventParams{
++		IssueID:     issueID,
++		ActorUserID: pgtype.Int8{Int64: actorUserID, Valid: actorUserID != 0},
++		Kind:        "assigned",
++		Meta:        []byte(`{"user_id":` + strconv.FormatInt(userID, 10) + `}`),
++	}); err != nil {
++		return err
++	}
++	if err := tx.Commit(ctx); err != nil {
++		return err
++	}
++	committed = true
++	return nil
++}
++
++// UnassignUser removes an assignee + emits an `unassigned` event.
++func UnassignUser(ctx context.Context, deps Deps, actorUserID, issueID, userID int64) error {
++	q := issuesdb.New()
++	tx, err := deps.Pool.Begin(ctx)
++	if err != nil {
++		return err
++	}
++	committed := false
++	defer func() {
++		if !committed {
++			_ = tx.Rollback(ctx)
++		}
++	}()
++	if err := q.UnassignUserFromIssue(ctx, tx, issuesdb.UnassignUserFromIssueParams{
++		IssueID: issueID, UserID: userID,
++	}); err != nil {
++		return err
++	}
++	if _, err := q.InsertIssueEvent(ctx, tx, issuesdb.InsertIssueEventParams{
++		IssueID:     issueID,
++		ActorUserID: pgtype.Int8{Int64: actorUserID, Valid: actorUserID != 0},
++		Kind:        "unassigned",
++		Meta:        []byte(`{"user_id":` + strconv.FormatInt(userID, 10) + `}`),
++	}); err != nil {
++		return err
++	}
++	if err := tx.Commit(ctx); err != nil {
++		return err
++	}
++	committed = true
++	return nil
++}

internal/issues/references.goadded

++// SPDX-License-Identifier: AGPL-3.0-or-later
++
++package issues
++
++import (
++	"context"
++	"errors"
++	"regexp"
++	"strconv"
++
++	"github.com/jackc/pgx/v5"
++	"github.com/jackc/pgx/v5/pgtype"
++
++	issuesdb "github.com/tenseleyFlow/shithub/internal/issues/sqlc"
++	reposdb "github.com/tenseleyFlow/shithub/internal/repos/sqlc"
++	usersdb "github.com/tenseleyFlow/shithub/internal/users/sqlc"
++)
++
++// Two patterns:
++//
++//   #N            — same-repo reference. Captured digits.
++//   owner/repo#N  — cross-repo reference. Captured owner, repo, digits.
++//
++// Word-boundary on the leading side so we don't grab "abc#1". The N is
++// limited to 1–9 leading digit + arbitrary digits, capped at 9 total to
++// keep crazy parses bounded.
++var (
++	reCrossRepoIssueRef = regexp.MustCompile(`(?:^|[^\w/])([A-Za-z0-9][A-Za-z0-9._-]*)/([A-Za-z0-9][A-Za-z0-9._-]*)#([0-9]{1,9})\b`)
++	reSameRepoIssueRef  = regexp.MustCompile(`(?:^|[^\w/])#([0-9]{1,9})\b`)
++)
++
++// insertReferencesFromBody parses `body` for cross-references and
++// records each one as an `issue_references` row plus a `referenced`
++// event on the *target* issue. Best-effort: malformed refs are skipped
++// silently. Self-references (target == source) are skipped to avoid
++// noise on the same issue's timeline.
++//
++// `source` is the source issue (for repo scoping when resolving #N).
++// `srcKind` is the issue_ref_source enum value. `srcObjectID` is the
++// ID of the comment / issue / push event that originated the ref.
++func insertReferencesFromBody(
++	ctx context.Context,
++	tx pgx.Tx,
++	deps Deps,
++	source issuesdb.Issue,
++	body string,
++	srcKind string,
++	srcObjectID int64,
++) error {
++	if body == "" {
++		return nil
++	}
++
++	q := issuesdb.New()
++	repoQ := reposdb.New()
++	userQ := usersdb.New()
++
++	seen := map[int64]struct{}{}
++
++	insertRef := func(targetID int64) error {
++		if targetID == source.ID {
++			return nil
++		}
++		if _, dup := seen[targetID]; dup {
++			return nil
++		}
++		seen[targetID] = struct{}{}
++		if err := q.InsertIssueReference(ctx, tx, issuesdb.InsertIssueReferenceParams{
++			TargetIssueID:  targetID,
++			SourceKind:     issuesdb.IssueRefSource(srcKind),
++			SourceIssueID:  pgtype.Int8{Int64: source.ID, Valid: true},
++			SourceObjectID: pgtype.Int8{Int64: srcObjectID, Valid: srcObjectID != 0},
++		}); err != nil {
++			return err
++		}
++		// Emit the timeline event on the *target* issue.
++		if _, err := q.InsertIssueEvent(ctx, tx, issuesdb.InsertIssueEventParams{
++			IssueID:     targetID,
++			ActorUserID: source.AuthorUserID,
++			Kind:        "referenced",
++			Meta:        []byte(`{"source_issue_id":` + strconv.FormatInt(source.ID, 10) + `}`),
++			RefTargetID: pgtype.Int8{Int64: source.ID, Valid: true},
++		}); err != nil {
++			return err
++		}
++		return nil
++	}
++
++	// Cross-repo: owner/repo#N
++	for _, m := range reCrossRepoIssueRef.FindAllStringSubmatch(body, -1) {
++		owner, name, numStr := m[1], m[2], m[3]
++		num, err := strconv.ParseInt(numStr, 10, 64)
++		if err != nil {
++			continue
++		}
++		u, err := userQ.GetUserByUsername(ctx, tx, owner)
++		if err != nil {
++			continue // org owners (S31) and unknown users get silently dropped
++		}
++		repo, err := repoQ.GetRepoByOwnerUserAndName(ctx, tx, reposdb.GetRepoByOwnerUserAndNameParams{
++			OwnerUserID: pgtype.Int8{Int64: u.ID, Valid: true},
++			Name:        name,
++		})
++		if err != nil {
++			continue
++		}
++		target, err := q.GetIssueByNumber(ctx, tx, issuesdb.GetIssueByNumberParams{
++			RepoID: repo.ID, Number: num,
++		})
++		if err != nil {
++			if errors.Is(err, pgx.ErrNoRows) {
++				continue
++			}
++			return err
++		}
++		if err := insertRef(target.ID); err != nil {
++			return err
++		}
++	}
++
++	// Same-repo: #N. Skip text positions already captured by the
++	// cross-repo regex by stripping owner/repo#N matches first.
++	stripped := reCrossRepoIssueRef.ReplaceAllString(body, " ")
++	for _, m := range reSameRepoIssueRef.FindAllStringSubmatch(stripped, -1) {
++		num, err := strconv.ParseInt(m[1], 10, 64)
++		if err != nil {
++			continue
++		}
++		target, err := q.GetIssueByNumber(ctx, tx, issuesdb.GetIssueByNumberParams{
++			RepoID: source.RepoID, Number: num,
++		})
++		if err != nil {
++			if errors.Is(err, pgx.ErrNoRows) {
++				continue
++			}
++			return err
++		}
++		if err := insertRef(target.ID); err != nil {
++			return err
++		}
++	}
++
++	return nil
++}
++
++// extractMentions returns deduplicated @username tokens from body.
++// Used by handlers / future notifications. Bounded by username regex.
++var reMention = regexp.MustCompile(`(?:^|[^\w])@([A-Za-z0-9][A-Za-z0-9_-]{0,38})\b`)
++
++func extractMentions(body string) []string {
++	if body == "" {
++		return nil
++	}
++	seen := map[string]struct{}{}
++	out := []string{}
++	for _, m := range reMention.FindAllStringSubmatch(body, -1) {
++		name := m[1]
++		if _, dup := seen[name]; dup {
++			continue
++		}
++		seen[name] = struct{}{}
++		out = append(out, name)
++	}
++	return out
++}

internal/issues/references_test.goadded

++// SPDX-License-Identifier: AGPL-3.0-or-later
++
++package issues
++
++import (
++	"reflect"
++	"sort"
++	"testing"
++)
++
++// findSameRepoRefs runs the regex used by the same-repo branch and
++// returns the parsed numbers. It mirrors the production loop modulo the
++// DB lookup, so the regex behavior can be unit-tested without a DB.
++func findSameRepoRefs(body string) []string {
++	stripped := reCrossRepoIssueRef.ReplaceAllString(body, " ")
++	out := []string{}
++	for _, m := range reSameRepoIssueRef.FindAllStringSubmatch(stripped, -1) {
++		out = append(out, m[1])
++	}
++	return out
++}
++
++func findCrossRepoRefs(body string) [][3]string {
++	out := [][3]string{}
++	for _, m := range reCrossRepoIssueRef.FindAllStringSubmatch(body, -1) {
++		out = append(out, [3]string{m[1], m[2], m[3]})
++	}
++	return out
++}
++
++func TestSameRepoRefRegex(t *testing.T) {
++	t.Parallel()
++	cases := []struct {
++		name string
++		body string
++		want []string
++	}{
++		{"plain", "fixes #1 and #42", []string{"1", "42"}},
++		{"sentence_start", "#7 should land", []string{"7"}},
++		{"no_word_prefix", "abc#1 isn't a ref", []string{}},
++		{"trailing_punct", "see #3, please", []string{"3"}},
++		{"line_start", "Done.\n#5 next", []string{"5"}},
++		// owner/repo#N must NOT also produce a same-repo hit on the #N
++		// portion; the cross-repo regex strips the whole token first.
++		{"cross_repo_excluded", "alice/repo#9 only", []string{}},
++	}
++	for _, c := range cases {
++		t.Run(c.name, func(t *testing.T) {
++			got := findSameRepoRefs(c.body)
++			sort.Strings(got)
++			sort.Strings(c.want)
++			if !reflect.DeepEqual(got, c.want) {
++				t.Errorf("body %q: got %v, want %v", c.body, got, c.want)
++			}
++		})
++	}
++}
++
++func TestCrossRepoRefRegex(t *testing.T) {
++	t.Parallel()
++	got := findCrossRepoRefs("see alice/proj#3 and bob/lib#42 for context, but not just #1")
++	want := [][3]string{
++		{"alice", "proj", "3"},
++		{"bob", "lib", "42"},
++	}
++	if !reflect.DeepEqual(got, want) {
++		t.Errorf("got %v, want %v", got, want)
++	}
++}
++
++func TestExtractMentions(t *testing.T) {
++	t.Parallel()
++	got := extractMentions("hi @alice and @bob, also @alice again — but not foo@example.com or a@b")
++	// `a@b` doesn't match (single-char user is fine but there's no
++	// leading word-boundary punctuation that's not a `@` itself, and
++	// our regex requires the `@` to be preceded by a non-word char or
++	// the start of input — `b a@b` would match `b` itself but `b@`
++	// fails the regex).
++	want := []string{"alice", "bob"}
++	if !reflect.DeepEqual(got, want) {
++		t.Errorf("got %v, want %v", got, want)
++	}
++}