trail

package
v0.6.0 Latest Latest
Warning

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

 Go to latest Published: May 4, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package trail provides types and helpers for managing trail metadata. Trails are branch-centric work tracking abstractions stored on the entire/trails/v1 orphan branch. They answer "why/what" (human intent) while checkpoints answer "how/when" (machine snapshots).

Index

Constants

This section is empty.

Variables

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

ErrTrailNotFound is returned when a trail cannot be found.

Functions

func HumanizeBranchName 

func HumanizeBranchName(branch string) string

HumanizeBranchName converts a branch name into a human-readable title. It strips common prefixes (feature/, fix/, etc.), replaces dashes/underscores with spaces, and capitalizes the first word.

func ValidateID 

func ValidateID(s string) error

ValidateID checks if a string is a valid trail ID format.

Types

type Author added in v0.6.0 

type Author struct {
	ID    string  `json:"id"`
	Login *string `json:"login"`
}

Author identifies the user who created a trail. On the wire the whole object may be null when the original author can no longer be resolved (e.g. the GitHub user no longer exists), and login may independently be null while the id is retained.

type CheckpointRef 

type CheckpointRef struct {
	CheckpointID string    `json:"checkpoint_id"`
	CommitSHA    string    `json:"commit_sha"`
	CreatedAt    time.Time `json:"created_at"`
	Summary      *string   `json:"summary"`
}

CheckpointRef links a checkpoint to a trail.

type Checkpoints 

type Checkpoints struct {
	Checkpoints []CheckpointRef `json:"checkpoints"`
}

Checkpoints holds the list of checkpoint references for a trail.

type Comment 

type Comment struct {
	ID         string         `json:"id"`
	Author     string         `json:"author"`
	Body       string         `json:"body"`
	CreatedAt  time.Time      `json:"created_at"`
	Resolved   bool           `json:"resolved"`
	ResolvedBy *string        `json:"resolved_by"`
	ResolvedAt *time.Time     `json:"resolved_at"`
	Replies    []CommentReply `json:"replies,omitempty"`
}

Comment represents a single comment on a trail.

type CommentReply 

type CommentReply struct {
	ID        string    `json:"id"`
	Author    string    `json:"author"`
	Body      string    `json:"body"`
	CreatedAt time.Time `json:"created_at"`
}

CommentReply represents a reply to a comment.

type Discussion 

type Discussion struct {
	Comments []Comment `json:"comments"`
}

Discussion holds the discussion/comments for a trail.

type ID 

type ID string

ID is a 12-character hex identifier for trails. 

const EmptyID ID = ""

EmptyID represents an unset or invalid trail ID.

func GenerateID 

func GenerateID() (ID, error)

GenerateID creates a new random 12-character hex trail ID.

func (ID) IsEmpty 

func (id ID) IsEmpty() bool

IsEmpty returns true if the trail ID is empty or unset.

func (ID) Path 

func (id ID) Path() string

Path returns the sharded storage path for this trail ID. Uses first 2 characters as shard (256 buckets), remaining as folder name. Example: "a3b2c4d5e6f7" -> "a3/b2c4d5e6f7"

func (ID) ShardParts 

func (id ID) ShardParts() (shard, suffix string)

ShardParts returns the shard prefix and suffix separately. Example: "a3b2c4d5e6f7" -> ("a3", "b2c4d5e6f7")

func (ID) String 

func (id ID) String() string

String returns the trail ID as a string.

type Metadata 

type Metadata struct {
	TrailID   ID         `json:"trail_id"`
	Branch    string     `json:"branch"`
	Base      string     `json:"base"`
	Title     string     `json:"title"`
	Body      string     `json:"body"`
	Status    Status     `json:"status"`
	Author    *Author    `json:"author"`
	Assignees []string   `json:"assignees"`
	Labels    []string   `json:"labels"`
	CreatedAt time.Time  `json:"created_at"`
	UpdatedAt time.Time  `json:"updated_at"`
	MergedAt  *time.Time `json:"merged_at"`
	Priority  Priority   `json:"priority,omitempty"`
	Type      Type       `json:"type,omitempty"`
	Reviewers []Reviewer `json:"reviewers,omitempty"`
}

Metadata represents the metadata for a trail, matching the web PR format.

func (*Metadata) AuthorLogin added in v0.6.0 

func (m *Metadata) AuthorLogin() string

AuthorLogin returns the trail author's login, or an empty string if the author is unknown (object null) or the login is null.

type Priority 

type Priority string

Priority represents the priority level of a trail. 

const (
	PriorityUrgent Priority = "urgent"
	PriorityHigh   Priority = "high"
	PriorityMedium Priority = "medium"
	PriorityLow    Priority = "low"
	PriorityNone   Priority = "none"
)

type Reviewer 

type Reviewer struct {
	Login  string         `json:"login"`
	Status ReviewerStatus `json:"status"`
}

Reviewer represents a reviewer assigned to a trail.

type ReviewerStatus 

type ReviewerStatus string

ReviewerStatus represents the review status for a reviewer. 

const (
	ReviewerPending          ReviewerStatus = "pending"
	ReviewerApproved         ReviewerStatus = "approved"
	ReviewerChangesRequested ReviewerStatus = "changes_requested"
)

type Status 

type Status string

Status represents the lifecycle status of a trail. 

const (
	StatusDraft      Status = "draft"
	StatusOpen       Status = "open"
	StatusInProgress Status = "in_progress"
	StatusInReview   Status = "in_review"
	StatusMerged     Status = "merged"
	StatusClosed     Status = "closed"
)

func ValidStatuses 

func ValidStatuses() []Status

ValidStatuses returns all valid trail statuses in lifecycle order.

func (Status) IsValid 

func (s Status) IsValid() bool

IsValid returns true if the status is a recognized trail status.

type Store 

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

Store provides CRUD operations for trail metadata on the entire/trails/v1 branch.

func NewStore 

func NewStore(repo *git.Repository) *Store

NewStore creates a new trail store backed by the given git repository.

func (*Store) AddCheckpoint 

func (s *Store) AddCheckpoint(ctx context.Context, trailID ID, ref CheckpointRef) error

AddCheckpoint prepends a checkpoint reference to a trail's checkpoints list (newest first). Only reads and writes the checkpoints.json file — metadata and discussion are untouched.

func (*Store) Delete 

func (s *Store) Delete(ctx context.Context, trailID ID) error

Delete removes a trail from the entire/trails/v1 branch.

func (*Store) EnsureBranch 

func (s *Store) EnsureBranch(ctx context.Context) error

EnsureBranch creates the entire/trails/v1 orphan branch if it doesn't exist.

func (*Store) FindByBranch 

func (s *Store) FindByBranch(branchName string) (*Metadata, error)

FindByBranch finds a trail for the given branch name. Returns (nil, nil) if no trail exists for the branch.

func (*Store) List 

func (s *Store) List() ([]*Metadata, error)

List returns all trail metadata from the entire/trails/v1 branch.

func (*Store) Read 

func (s *Store) Read(trailID ID) (*Metadata, *Discussion, *Checkpoints, error)

Read reads a trail by its ID from the entire/trails/v1 branch.

func (*Store) Update 

func (s *Store) Update(ctx context.Context, trailID ID, updateFn func(*Metadata)) error

Update updates an existing trail's metadata. It reads the current metadata, applies the provided update function, and writes it back.

func (*Store) Write 

func (s *Store) Write(ctx context.Context, metadata *Metadata, discussion *Discussion, checkpoints *Checkpoints) error

Write writes trail metadata, discussion, and checkpoints to the entire/trails/v1 branch. If checkpoints is nil, an empty checkpoints list is written.

type Type 

type Type string

Type represents the type/category of a trail. 

const (
	TypeBug      Type = "bug"
	TypeFeature  Type = "feature"
	TypeChore    Type = "chore"
	TypeDocs     Type = "docs"
	TypeRefactor Type = "refactor"
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.