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). Nothing calls tracker.Client yet.
Index ¶
- Variables
- func IsNotFound(err error) bool
- type Body
- type Client
- type Comment
- type FakeJiraClient
- func (f *FakeJiraClient) CreateComment(_ context.Context, issueIDOrKey, body string) (*jira.Comment, error)
- func (f *FakeJiraClient) GetIssue(_ context.Context, issueIDOrKey string) (*jira.Issue, error)
- func (f *FakeJiraClient) ListComments(_ context.Context, issueIDOrKey string) ([]jira.Comment, error)
- func (f *FakeJiraClient) UpdateComment(_ context.Context, issueIDOrKey, commentID, body string) error
- type ForgeClient
- func (c *ForgeClient) CreateComment(ctx context.Context, project string, number int, body Body) (*Comment, error)
- func (c *ForgeClient) GetIssue(ctx context.Context, project string, number int) (*Issue, error)
- func (c *ForgeClient) ListComments(ctx context.Context, project string, number int) ([]Comment, error)
- func (c *ForgeClient) UpdateComment(ctx context.Context, project string, number int, commentID string, body Body) error
- type Issue
- type JiraClient
- func (c *JiraClient) CreateComment(ctx context.Context, project string, number int, body Body) (*Comment, error)
- func (c *JiraClient) GetIssue(ctx context.Context, project string, number int) (*Issue, error)
- func (c *JiraClient) ListComments(ctx context.Context, project string, number int) ([]Comment, error)
- func (c *JiraClient) UpdateComment(ctx context.Context, project string, number int, commentID string, body Body) error
Constants ¶
This section is empty.
Variables ¶
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.
Functions ¶
func IsNotFound ¶
IsNotFound reports whether err indicates a requested issue or comment was not found.
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
}
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 ¶
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
CreatedBody string
UpdatedIssueKey string
UpdatedCommentID string
UpdatedBody string
}
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 (*FakeJiraClient) ListComments ¶ added in v0.37.0
func (*FakeJiraClient) UpdateComment ¶ added in v0.37.0
func (f *FakeJiraClient) UpdateComment(_ context.Context, issueIDOrKey, commentID, body string) error
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) 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) GetIssue ¶
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 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) 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) ListComments ¶ added in v0.37.0
func (c *JiraClient) ListComments(ctx context.Context, project string, number int) ([]Comment, error)
ListComments implements Client.
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.