tracker

package
v0.37.0 Latest Latest
Warning

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

Go to latest
Published: Aug 23, 2026 License: Apache-2.0 Imports: 8 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). Nothing calls tracker.Client yet.

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.

Functions

func IsNotFound

func IsNotFound(err error) bool

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

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

	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 (f *FakeJiraClient) CreateComment(_ context.Context, issueIDOrKey, body string) (*jira.Comment, error)

func (*FakeJiraClient) GetIssue added in v0.37.0

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

func (*FakeJiraClient) ListComments added in v0.37.0

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

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

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
}

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) 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) GetIssue added in v0.37.0

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

GetIssue implements Client.

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.

Jump to

Keyboard shortcuts

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