tracker

package
v0.47.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 11, 2026 License: Apache-2.0 Imports: 9 Imported by: 0

Documentation

Overview

Package tracker defines a narrow, forge-agnostic interface for reading and writing issue content (title, body, comments), keyed by (project string, number int) rather than the (owner, repo string, number int) shape used by forge.Client.

forge.Client already covers this surface for GitHub and GitLab, but it stays scoped to git-hosting operations — Jira is explicitly not a forge (it has no branches, pull requests, or CI). Keying by a single project string lets a future Jira implementation use its natural project key (e.g. "PROJECT") instead of forcing an owner/repo split that Jira doesn't have; the issue number is passed separately, as with GitHub and GitLab.

This package only defines the interface and thin adapters over forge.Client (see ForgeClient). Consumers include statuscomment (run-status notifications) and reconcilestatus (orphan cleanup).

Index

Constants

This section is empty.

Variables

View Source
var ErrNotFound = errors.New("not found")

ErrNotFound indicates a requested issue or comment was not found. Implementations of Client must return an error satisfying errors.Is(err, ErrNotFound) — checkable via IsNotFound — for missing resources, rather than requiring callers to reach into a specific tracker backend (e.g. forge.ErrNotFound) to detect this case.

View Source
var ErrNotSupported = errors.New("not supported by this tracker")

ErrNotSupported indicates the tracker backend does not support the requested operation (e.g. typed issue links on GitHub or GitLab).

View Source
var FakeJiraBot = jira.User{AccountID: "fake-bot-account-id", DisplayName: "fullsend-bot"}

FakeJiraBot is the account a FakeJiraClient posts as by default.

Functions

func IsNotFound

func IsNotFound(err error) bool

IsNotFound reports whether err indicates a requested issue or comment was not found.

func IsNotSupported added in v0.46.0

func IsNotSupported(err error) bool

IsNotSupported reports whether err indicates the tracker backend does not support the requested operation.

func NewFakeJiraClientWithFake added in v0.40.0

func NewFakeJiraClientWithFake(baseURL string) (*JiraClient, *FakeJiraClient, error)

NewFakeJiraClientWithFake returns both the tracker.Client and the underlying FakeJiraClient, giving tests access to the fake's control fields (e.g. PropertyError for permission failure simulation).

Types

type Body

type Body string

Body is Markdown-formatted issue/comment text, as produced by GitHub and GitLab. Jira doesn't speak Markdown — its v3 API requires comment and description bodies in Atlassian Document Format (ADF) and rejects plain strings outright. A Jira Client implementation is responsible for converting Body to and from ADF; a naive pass-through (wrapping the raw Markdown string in a single ADF text node) doesn't just lose formatting, it actively corrupts content — Jira's plain-text rendering path interprets stray Markdown characters (e.g. braces in code samples) as wiki-markup and mangles the surrounding text.

type Client

type Client interface {
	// GetIssue returns the issue identified by project and number.
	GetIssue(ctx context.Context, project string, number int) (*Issue, error)
	// ListComments returns all comments on the issue identified by project and number.
	ListComments(ctx context.Context, project string, number int) ([]Comment, error)
	// CreateComment adds a new comment with the given body to the issue.
	CreateComment(ctx context.Context, project string, number int, body Body) (*Comment, error)
	// UpdateComment updates the body of commentID on the issue (project, number).
	// number is included because Jira requires the issue key to update a comment.
	UpdateComment(ctx context.Context, project string, number int, commentID string, body Body) error
	// DeleteComment removes the comment identified by commentID from the issue.
	// number is included because Jira requires the issue key to delete a comment.
	DeleteComment(ctx context.Context, project string, number int, commentID string) error
}

Client abstracts issue-content read/write operations across trackers (GitHub, GitLab, and eventually Jira). Project identifies the issue's container: "owner/repo" for GitHub/GitLab, a Jira project key for Jira.

Implementations must return an error satisfying IsNotFound when the requested issue or comment doesn't exist.

type Comment

type Comment struct {
	ID        string
	HTMLURL   string
	Body      Body
	Author    string
	CreatedAt string
}

Comment represents a comment on an issue.

ID is a string for JSON round-tripping safety and to allow for non-numeric IDs from a possible future tracker, even though GitHub, GitLab, and Jira comment IDs are all numeric under the hood. Callers that need to update a comment pass the ID back verbatim via UpdateComment.

type FakeJiraClient added in v0.37.0

type FakeJiraClient struct {
	Issues   map[string]*jira.Issue
	Comments map[string][]jira.Comment

	// CommentProperties maps "issueKey/commentID" to a map of
	// propertyKey -> value, mirroring Jira's per-comment entity
	// property store.
	CommentProperties map[string]map[string]json.RawMessage

	CreatedBody      string
	UpdatedIssueKey  string
	UpdatedCommentID string
	UpdatedBody      string

	// PropertyError, when non-nil, is returned by SetCommentProperty
	// to simulate permission failures.
	PropertyError error

	// UpdateError, when non-nil, is returned by UpdateComment to
	// simulate update failures.
	UpdateError error

	// Myself is the account GetMyself returns and new comments are
	// authored by; the zero value means FakeJiraBot. MyselfError, when
	// non-nil, is returned by GetMyself.
	Myself      jira.User
	MyselfError error

	// Links records every LinkIssues call in order. LinkError, when
	// non-nil, is returned by LinkIssues instead of recording the link.
	Links     []FakeJiraLink
	LinkError error
}

FakeJiraClient is an in-memory fake implementing the jiraClient interface, exported (unlike its ecosystem forge.FakeClient counterpart, which lives alongside it) so tests in other packages can exercise tracker.Client's Jira path — including its real jira.MarkdownToADF/ADFToMarkdown round-trip — without a live Jira instance. CreateComment/UpdateComment store the body as real ADF (mirroring Jira echoing back what it stored), so ListComments/GetIssue read it back through the same escaping/decoding logic a live Jira instance would apply.

func (*FakeJiraClient) CreateComment added in v0.37.0

func (f *FakeJiraClient) CreateComment(ctx context.Context, issueIDOrKey, body string) (*jira.Comment, error)

func (*FakeJiraClient) CreateCommentWithProperties added in v0.40.0

func (f *FakeJiraClient) CreateCommentWithProperties(_ context.Context, issueIDOrKey, body string, properties []jira.CommentProperty) (*jira.Comment, error)

func (*FakeJiraClient) DeleteComment added in v0.40.0

func (f *FakeJiraClient) DeleteComment(_ context.Context, issueIDOrKey, commentID string) error

func (*FakeJiraClient) GetIssue added in v0.37.0

func (f *FakeJiraClient) GetIssue(_ context.Context, issueIDOrKey string) (*jira.Issue, error)

func (*FakeJiraClient) GetMyself added in v0.44.0

func (f *FakeJiraClient) GetMyself(_ context.Context) (*jira.User, error)

func (*FakeJiraClient) LinkIssues added in v0.46.0

func (f *FakeJiraClient) LinkIssues(_ context.Context, inwardIssueKey, outwardIssueKey, linkTypeName string) error

func (*FakeJiraClient) ListComments added in v0.37.0

func (f *FakeJiraClient) ListComments(_ context.Context, issueIDOrKey string) ([]jira.Comment, error)

func (*FakeJiraClient) SetCommentProperty added in v0.40.0

func (f *FakeJiraClient) SetCommentProperty(_ context.Context, issueIDOrKey, commentID, propertyKey string, value any) error

func (*FakeJiraClient) UpdateComment added in v0.37.0

func (f *FakeJiraClient) UpdateComment(_ context.Context, issueIDOrKey, commentID, body string) error
type FakeJiraLink struct {
	Type         string
	InwardIssue  string
	OutwardIssue string
}

FakeJiraLink is an issue link recorded by FakeJiraClient.LinkIssues.

type ForgeClient

type ForgeClient struct {
	// contains filtered or unexported fields
}

ForgeClient adapts a forge.Client to the tracker.Client interface. It works for both the GitHub and GitLab forge.Client implementations, since forge.Client already abstracts over the two — this adapter only needs to split the tracker's single "project" string back into the owner/repo pair that forge.Client expects, and convert forge.IssueComment's numeric ID to the string form tracker.Comment uses.

func NewForgeClient

func NewForgeClient(fc forge.Client) *ForgeClient

NewForgeClient returns a tracker.Client backed by fc.

func (*ForgeClient) AddCommentReaction added in v0.40.0

func (c *ForgeClient) AddCommentReaction(ctx context.Context, project string, number int, commentID string, content string) (int64, error)

AddCommentReaction implements Reactor by splitting project into owner/repo for the underlying forge call.

func (*ForgeClient) AddIssueReaction added in v0.40.0

func (c *ForgeClient) AddIssueReaction(ctx context.Context, project string, number int, content string) (int64, error)

AddIssueReaction implements Reactor by splitting project into owner/repo for the underlying forge call.

func (*ForgeClient) AuthenticatedUser added in v0.44.0

func (c *ForgeClient) AuthenticatedUser(ctx context.Context) (string, error)

AuthenticatedUser returns the login the underlying forge client is authenticated as, so a caller can tell the bot's own comments from anyone else's.

func (*ForgeClient) CreateComment

func (c *ForgeClient) CreateComment(ctx context.Context, project string, number int, body Body) (*Comment, error)

CreateComment implements Client by splitting project into owner/repo for the underlying forge call.

func (*ForgeClient) DeleteComment added in v0.40.0

func (c *ForgeClient) DeleteComment(ctx context.Context, project string, number int, commentID string) error

DeleteComment implements Client by splitting project into owner/repo for the underlying forge call.

func (*ForgeClient) DeleteCommentReaction added in v0.40.0

func (c *ForgeClient) DeleteCommentReaction(ctx context.Context, project string, number int, commentID string, reactionID int64) error

DeleteCommentReaction implements Reactor by splitting project into owner/repo for the underlying forge call.

func (*ForgeClient) DeleteIssueReaction added in v0.40.0

func (c *ForgeClient) DeleteIssueReaction(ctx context.Context, project string, number int, reactionID int64) error

DeleteIssueReaction implements Reactor by splitting project into owner/repo for the underlying forge call.

func (*ForgeClient) GetIssue

func (c *ForgeClient) GetIssue(ctx context.Context, project string, number int) (*Issue, error)

GetIssue implements Client by splitting project into owner/repo for the underlying forge call.

func (*ForgeClient) ListComments

func (c *ForgeClient) ListComments(ctx context.Context, project string, number int) ([]Comment, error)

ListComments implements Client by splitting project into owner/repo for the underlying forge call.

func (*ForgeClient) UpdateComment

func (c *ForgeClient) UpdateComment(ctx context.Context, project string, number int, commentID string, body Body) error

UpdateComment implements Client. number is unused here: forge.Client's UpdateIssueComment takes only a comment ID, which is sufficient for GitHub (comment IDs are globally unique within the repo). GitLab actually needs the issue/MR IID to address a note directly — see gitlab.LiveClient.updateOrDeleteNote — but forge.Client's UpdateIssueComment doesn't expose one, so the GitLab path still falls back to that method's documented scan. Jira needs the issue key for an unrelated reason: it isn't a forge.Client implementation at all.

type Issue

type Issue struct {
	Number int
	Title  string
	Body   Body
	URL    string
	Labels []string
	// IssueType is the tracker's issue type name (e.g. "Bug", "Story").
	// Set by the Jira client; empty for trackers that don't report one.
	IssueType string
	// CustomFields maps tracker-specific custom field IDs (e.g. Jira's
	// "customfield_10875") to their raw JSON values. Set by the Jira
	// client; nil for GitHub and GitLab.
	CustomFields map[string]json.RawMessage
}

Issue represents an issue's content, independent of the tracker backend.

type JiraClient added in v0.37.0

type JiraClient struct {
	// contains filtered or unexported fields
}

JiraClient adapts a Jira client to tracker.Client. project is a Jira project key (e.g. "PROJ"); (project, number) maps to the issue key "PROJ-123".

func NewFakeJiraClient added in v0.37.0

func NewFakeJiraClient(baseURL string) (*JiraClient, error)

NewFakeJiraClient returns a tracker.Client backed by an in-memory fake that round-trips comment bodies through the real jira.MarkdownToADF/ADFToMarkdown conversions, for tests that need to exercise Jira-specific markdown quirks (e.g. mdEscaper) without a live Jira instance.

func NewJiraClient added in v0.37.0

func NewJiraClient(jc jiraClient, baseURL string) (*JiraClient, error)

NewJiraClient returns a tracker.Client backed by jc. baseURL is the Jira instance's base URL (e.g. "https://acme.atlassian.net"), used to build issue browse URLs. Returns an error if baseURL embeds credentials (https://user:token@host): those would otherwise propagate into every Issue.URL this client returns, which are commonly logged or displayed.

func (*JiraClient) AuthenticatedUser added in v0.44.0

func (c *JiraClient) AuthenticatedUser(ctx context.Context) (string, error)

AuthenticatedUser returns the account ID this client is authenticated as (GET /myself), so a caller can tell its own comments from anyone else's by Comment.Author.AccountID. Display names are not identities.

func (*JiraClient) CreateComment added in v0.37.0

func (c *JiraClient) CreateComment(ctx context.Context, project string, number int, body Body) (*Comment, error)

CreateComment implements Client. The returned Comment's Body is ADFToMarkdown(comment.Body), the same representation ListComments uses, so tracker.Comment.Body has a stable meaning regardless of which method produced it.

func (*JiraClient) CreateCommentWithMarker added in v0.40.0

func (c *JiraClient) CreateCommentWithMarker(ctx context.Context, project string, number int, body Body, marker string) (*Comment, error)

CreateCommentWithMarker creates a comment with the sticky marker stored as a Jira comment entity property instead of embedded in the visible ADF body. This keeps implementation bookkeeping out of the user-visible conversation on Jira (which lacks HTML comments and would render the marker as plain text).

func (*JiraClient) CreateStatusComment added in v0.40.0

func (c *JiraClient) CreateStatusComment(ctx context.Context, project string, number int, body Body, marker string, terminal bool) (*Comment, error)

CreateStatusComment implements StatusCommentClient by storing run identity and terminal state in a Jira comment entity property.

func (*JiraClient) DeleteComment added in v0.40.0

func (c *JiraClient) DeleteComment(ctx context.Context, project string, number int, commentID string) error

DeleteComment implements Client.

func (*JiraClient) FindCommentByMarkerProperty added in v0.40.0

func (c *JiraClient) FindCommentByMarkerProperty(comments []jira.Comment, marker string) *jira.Comment

FindCommentByMarkerProperty returns the first comment that carries the sticky marker as a comment entity property, or nil if none is found. This is the property-based equivalent of the body-scanning approach used for GitHub/GitLab.

If no property match is found, a legacy fallback scans comment bodies for the marker string (the old behavior before property-based storage). This allows transparent migration: the first update to a legacy comment will set the property and strip the marker from the body.

func (*JiraClient) FindStatusComment added in v0.40.0

func (c *JiraClient) FindStatusComment(ctx context.Context, project string, number int, marker string) (*Comment, bool, error)

FindStatusComment implements StatusCommentClient. Property lookup is the primary path; visible-body scanning keeps pre-property comments compatible.

func (*JiraClient) GetIssue added in v0.37.0

func (c *JiraClient) GetIssue(ctx context.Context, project string, number int) (*Issue, error)

GetIssue implements Client.

func (*JiraClient) IsStatusComment added in v0.40.0

func (c *JiraClient) IsStatusComment(ctx context.Context, project string, number int, commentID string) (bool, error)

IsStatusComment implements StatusCommentClient. The legacy body check keeps timeline analysis correct while older marker-bearing comments are present.

func (*JiraClient) LinkIssues added in v0.46.0

func (c *JiraClient) LinkIssues(ctx context.Context, fromProject string, fromNumber int, toProject string, toNumber int, linkType string) error

LinkIssues implements Linker. The from issue is sent as Jira's inwardIssue and the to issue as its outwardIssue, so Jira records the link in the link type's outward direction: for "Blocks", the from issue blocks the to issue.

func (*JiraClient) ListComments added in v0.37.0

func (c *JiraClient) ListComments(ctx context.Context, project string, number int) ([]Comment, error)

ListComments implements Client.

func (*JiraClient) ListJiraComments added in v0.40.0

func (c *JiraClient) ListJiraComments(ctx context.Context, project string, number int) ([]jira.Comment, error)

ListJiraComments returns the raw jira.Comment objects (including entity properties) for use by FindCommentByMarkerProperty. This is separate from ListComments because the generic tracker.Comment type does not carry Jira-specific property data.

func (*JiraClient) MigrateAndUpdateComment added in v0.40.0

func (c *JiraClient) MigrateAndUpdateComment(ctx context.Context, project string, number int, commentID string, body Body, marker string) error

MigrateAndUpdateComment updates a comment's body and ensures the sticky marker is stored as a comment entity property. If the comment was found via the legacy body-text path (no property set), this also sets the property — transparently migrating the comment to the property-based scheme.

The body written to Jira has the marker stripped (unlike GitHub/GitLab where the marker is an invisible HTML comment). The caller should pass the body without the marker prefix.

func (*JiraClient) UpdateComment added in v0.37.0

func (c *JiraClient) UpdateComment(ctx context.Context, project string, number int, commentID string, body Body) error

UpdateComment implements Client. Unlike GitHub/GitLab, Jira's update-comment endpoint needs the issue key, which is why number is part of the signature here.

func (*JiraClient) UpdateStatusComment added in v0.40.0

func (c *JiraClient) UpdateStatusComment(ctx context.Context, project string, number int, commentID string, body Body, marker string, terminal bool) error

UpdateStatusComment implements StatusCommentClient. Writing the property first preserves discoverability if the subsequent body update fails.

type Linker added in v0.46.0

type Linker interface {
	// LinkIssues creates a link of type linkType from the issue
	// (fromProject, fromNumber) to the issue (toProject, toNumber).
	// linkType is passed through verbatim; its valid values and
	// direction semantics are tracker-specific (for Jira, link type
	// names such as "Blocks" are instance-specific).
	LinkIssues(ctx context.Context, fromProject string, fromNumber int, toProject string, toNumber int, linkType string) error
}

Linker is an optional capability for creating typed links between issues. Jira implements it with issue links; GitHub and GitLab have no first-class typed issue links and do not implement it. Consumers should type-assert their tracker.Client to Linker and report ErrNotSupported when the tracker does not implement it.

type Reactor added in v0.40.0

type Reactor interface {
	// AddIssueReaction adds an emoji reaction to an issue or pull request.
	// content is the reaction type (e.g. "eyes", "+1", "confused").
	AddIssueReaction(ctx context.Context, project string, number int, content string) (id int64, err error)
	// DeleteIssueReaction removes a previously added issue reaction by ID.
	DeleteIssueReaction(ctx context.Context, project string, number int, reactionID int64) error
	// AddCommentReaction adds an emoji reaction to a specific comment.
	AddCommentReaction(ctx context.Context, project string, number int, commentID string, content string) (id int64, err error)
	// DeleteCommentReaction removes a previously added comment reaction by ID.
	DeleteCommentReaction(ctx context.Context, project string, number int, commentID string, reactionID int64) error
}

Reactor is an optional capability for adding and removing emoji reactions on issues and comments. Tracker reaction support varies: GitHub and GitLab support reactions on both issues and comments; Jira Cloud supports reactions on comments but not on issues. Because the interface includes issue-level reactions, JiraClient does not implement Reactor currently — adding Jira comment-reaction support is straightforward once needed. Consumers should type-assert their tracker.Client to Reactor before calling reaction methods and silently skip reactions when the tracker does not implement it.

type StatusCommentClient added in v0.40.0

type StatusCommentClient interface {
	CreateStatusComment(ctx context.Context, project string, number int, body Body, marker string, terminal bool) (*Comment, error)
	UpdateStatusComment(ctx context.Context, project string, number int, commentID string, body Body, marker string, terminal bool) error
	FindStatusComment(ctx context.Context, project string, number int, marker string) (comment *Comment, terminal bool, err error)
	IsStatusComment(ctx context.Context, project string, number int, commentID string) (bool, error)
}

StatusCommentClient is an optional capability for trackers that can store run-status identity and lifecycle state outside the visible comment body. Jira implements this with comment entity properties. Trackers without this capability keep using invisible HTML markers in comment bodies.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL