tracker

Documentation

Overview

Package tracker implements filesystem-based issue storage and retrieval.

Index

• func FilterEventsByTime(events []model.Event, since, until time.Time) []model.Event
• func FilterIssues(issues []model.Issue, opts FilterOptions) []model.Issue
• func SortIssues(issues []model.Issue, sortBy string)
• func ValidateTransition(cfg model.Config, from, to string) error
• func ValidateType(cfg model.Config, issueType string) error
• type EventWithIssue
  • func FilterEventsWithIssueByTime(events []EventWithIssue, since, until time.Time) []EventWithIssue
• type FilterOptions
• type LogEntry
• type Tracker
  • func Init(root string) (*Tracker, error)
  • func Load(root string) (*Tracker, error)
  • func (t *Tracker) AddComment(id, text, user string) (model.Issue, error)
  • func (t *Tracker) AppendEvent(id string, event model.Event) error
  • func (t *Tracker) AppendLog(issue model.Issue) error
  • func (t *Tracker) CompactAllDone() ([]string, error)
  • func (t *Tracker) CompactIssue(id string) error
  • func (t *Tracker) CreateIssue(title, description, assignee string, priority int, labels []string, ...) (model.Issue, error)
  • func (t *Tracker) DeduplicateLog() (int, error)
  • func (t *Tracker) GarbageCollect(maxAgeDays int) ([]string, error)
  • func (t *Tracker) GenerateID() (string, error)
  • func (t *Tracker) LinkIssue(childID, parentID, user string) (model.Issue, error)
  • func (t *Tracker) ListIssues() ([]model.Issue, error)
  • func (t *Tracker) LoadAllEvents() ([]EventWithIssue, error)
  • func (t *Tracker) LoadEvents(issueID string) ([]model.Event, error)
  • func (t *Tracker) LoadIssue(id string) (model.Issue, error)
  • func (t *Tracker) LoadLog() ([]LogEntry, error)
  • func (t *Tracker) PurgeIssue(issue model.Issue) error
  • func (t *Tracker) ResolvePrefix(prefix string) (string, error)
  • func (t *Tracker) RewriteAllIssues() (int, error)
  • func (t *Tracker) SaveIssue(issue model.Issue) error
  • func (t *Tracker) SetStatus(id, newStatus, user string) (model.Issue, error)
  • func (t *Tracker) UnlinkIssue(childID, user string) (model.Issue, error)

Functions

func FilterEventsByTime

func FilterEventsByTime(events []model.Event, since, until time.Time) []model.Event

FilterEventsByTime returns events within the given time window. Zero-value since/until means no bound on that side.

func FilterIssues

func FilterIssues(issues []model.Issue, opts FilterOptions) []model.Issue

FilterIssues returns the subset of issues matching all specified filters.

func SortIssues

func SortIssues(issues []model.Issue, sortBy string)

SortIssues sorts issues in place by the given field. Supported: "priority" (ascending), "updated" (newest first), "created" (newest first, default), "title" (alphabetically).

func ValidateTransition

func ValidateTransition(cfg model.Config, from, to string) error

ValidateTransition checks if moving from one state to another is allowed by config.

func ValidateType

func ValidateType(cfg model.Config, issueType string) error

ValidateType checks if the given type is allowed by config.

Types

type EventWithIssue

type EventWithIssue struct {
	model.Event
	IssueID string
}

EventWithIssue pairs an event with the issue ID it belongs to.

func FilterEventsWithIssueByTime

func FilterEventsWithIssueByTime(events []EventWithIssue, since, until time.Time) []EventWithIssue

FilterEventsWithIssueByTime is like FilterEventsByTime but for EventWithIssue slices.

type FilterOptions

type FilterOptions struct {
	Status          string
	ExcludeStatuses []string
	Label           string
	Assignee        string
	Priority        int
	HasPriority     bool // distinguishes "filter by priority 0" from "no filter"
	Type            string
	ParentID        string
	RootsOnly       bool
}

FilterOptions specifies criteria for filtering issues. All non-zero fields are combined with AND logic.

type LogEntry

type LogEntry struct {
	ID      string    `json:"id"`
	Title   string    `json:"title"`
	Type    string    `json:"type"`
	Status  string    `json:"status"`
	Labels  []string  `json:"labels,omitempty"`
	Created time.Time `json:"created"`
	Closed  time.Time `json:"closed"`
}

LogEntry represents a completed issue in the completion log.

type Tracker

type Tracker struct {
	Root   string
	Config model.Config
}

func Init

func Init(root string) (*Tracker, error)

Init creates the .work directory structure and writes the default config. If config.json already exists, it is loaded and preserved.

func Load

func Load(root string) (*Tracker, error)

Load reads an existing tracker from disk.

func (*Tracker) AddComment

func (t *Tracker) AddComment(id, text, user string) (model.Issue, error)

AddComment appends a comment to the issue and records a history event.

func (*Tracker) AppendEvent

func (t *Tracker) AppendEvent(id string, event model.Event) error

AppendEvent writes an event as a JSON line to the issue's history.jsonl.

func (*Tracker) AppendLog

func (t *Tracker) AppendLog(issue model.Issue) error

AppendLog writes a one-line JSON entry to .work/log.jsonl. Skips writing if the issue ID already exists in the log.

func (*Tracker) CompactAllDone

func (t *Tracker) CompactAllDone() ([]string, error)

CompactAllDone compacts all done/cancelled issues.

func (*Tracker) CompactIssue

func (t *Tracker) CompactIssue(id string) error

CompactIssue strips a completed issue to minimal metadata. Logs to .work/log.jsonl, truncates description, clears comments, and compacts history to create + close events only.

func (*Tracker) CreateIssue

func (t *Tracker) CreateIssue(title, description, assignee string, priority int, labels []string, issueType, parentID, user string) (model.Issue, error)

CreateIssue generates an ID, saves the issue, and records a creation event.

func (*Tracker) DeduplicateLog

func (t *Tracker) DeduplicateLog() (int, error)

DeduplicateLog removes duplicate entries from log.jsonl, keeping the first occurrence of each issue ID. Returns the number of duplicates removed.

func (*Tracker) GarbageCollect

func (t *Tracker) GarbageCollect(maxAgeDays int) ([]string, error)

GarbageCollect removes issue directories for issues completed more than maxAgeDays ago. Logs each issue before deletion.

func (*Tracker) GenerateID

func (t *Tracker) GenerateID() (string, error)

GenerateID produces a random hex string of the configured length.

func (*Tracker) LinkIssue

func (t *Tracker) LinkIssue(childID, parentID, user string) (model.Issue, error)

LinkIssue sets the parent of a child issue. Validates that the parent exists, neither issue creates a grandchild relationship, and no circular ref.

func (*Tracker) ListIssues

func (t *Tracker) ListIssues() ([]model.Issue, error)

ListIssues loads all issues from the tracker.

func (*Tracker) LoadAllEvents

func (t *Tracker) LoadAllEvents() ([]EventWithIssue, error)

LoadAllEvents reads events from every issue, annotated with issue ID.

func (*Tracker) LoadEvents

func (t *Tracker) LoadEvents(issueID string) ([]model.Event, error)

LoadEvents reads all events from an issue's history.jsonl. Returns empty slice (not error) if the file doesn't exist.

func (*Tracker) LoadIssue

func (t *Tracker) LoadIssue(id string) (model.Issue, error)

LoadIssue reads an issue from its directory.

func (*Tracker) LoadLog

func (t *Tracker) LoadLog() ([]LogEntry, error)

LoadLog reads all entries from .work/log.jsonl.

func (*Tracker) PurgeIssue

func (t *Tracker) PurgeIssue(issue model.Issue) error

PurgeIssue logs an issue to the completion log and removes its directory.

func (*Tracker) ResolvePrefix

func (t *Tracker) ResolvePrefix(prefix string) (string, error)

ResolvePrefix finds an issue ID matching the given prefix. Returns an error if zero or multiple issues match.

func (*Tracker) RewriteAllIssues

func (t *Tracker) RewriteAllIssues() (int, error)

RewriteAllIssues loads every issue and re-saves it, migrating to the current on-disk format (e.g. compact JSON).

func (*Tracker) SaveIssue

func (t *Tracker) SaveIssue(issue model.Issue) error

SaveIssue writes an issue to its directory.

func (*Tracker) SetStatus

func (t *Tracker) SetStatus(id, newStatus, user string) (model.Issue, error)

SetStatus validates the transition and updates the issue's status.

func (*Tracker) UnlinkIssue

func (t *Tracker) UnlinkIssue(childID, user string) (model.Issue, error)

UnlinkIssue removes the parent from a child issue.