tracking

Documentation

Overview

Package tracking integrates supplementary tracking data from Google Sheets or CSV files into the burndown pipeline. Tracking data is supplementary — the application works perfectly without it.

Index

• func NormalizePath(p string) string
• type CSVSource
  • func (s *CSVSource) Load(_ context.Context) (*TrackingData, error)
• type ContributorMap
  • func NewContributorMap(contributors []config.Contributor) *ContributorMap
  • func (cm *ContributorMap) Resolve(owner string) *config.Contributor
  • func (cm *ContributorMap) Summarize(entries []TrackingEntry) (summaries []OwnerSummary, unresolvedOwners []string)
  • func (cm *ContributorMap) UnresolvedOwners(entries []TrackingEntry) []string
• type OwnerSummary
• type SheetsSource
  • func (s *SheetsSource) Load(ctx context.Context) (*TrackingData, error)
• type Source
  • func ResolveSource(cfg *config.Config) Source
• type TrackingData
  • func (td *TrackingData) ByPath() map[string]*TrackingEntry
• type TrackingEntry

Functions

func NormalizePath

func NormalizePath(p string) string

NormalizePath strips leading slashes/dots and lowercases for consistent matching.

Types

type CSVSource

type CSVSource struct {
	Path string
}

CSVSource reads tracking data from a local CSV file.

func (*CSVSource) Load

func (s *CSVSource) Load(_ context.Context) (*TrackingData, error)

type ContributorMap

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

ContributorMap provides fast lookup of contributors from free-text owner strings.

func NewContributorMap

func NewContributorMap(contributors []config.Contributor) *ContributorMap

NewContributorMap builds lookup indices over the given contributors list.

func (*ContributorMap) Resolve

func (cm *ContributorMap) Resolve(owner string) *config.Contributor

Resolve matches a free-text owner string against the contributor list. Returns nil if no match is found or owner is empty.

Matching rules (tried in order):

1. Exact match on GitHub handle (case-insensitive, strips leading "@")
2. Exact match on full Name (case-insensitive)
3. Prefix match on first name from Name (case-insensitive, only if unambiguous)

func (*ContributorMap) Summarize

func (cm *ContributorMap) Summarize(entries []TrackingEntry) (summaries []OwnerSummary, unresolvedOwners []string)

Summarize aggregates tracking entries by resolved contributor. It returns per-contributor summaries and a deduplicated, sorted list of owner strings that could not be resolved to any known contributor.

func (*ContributorMap) UnresolvedOwners

func (cm *ContributorMap) UnresolvedOwners(entries []TrackingEntry) []string

UnresolvedOwners returns a deduplicated, sorted list of owner strings from the given tracking entries that do not resolve to any known contributor.

type OwnerSummary

type OwnerSummary struct {
	Name             string
	GitHub           string
	SlackID          string
	Total            int
	Done             int
	InProgress       int
	Blocked          int
	NotStarted       int
	UnresolvedOwners []string // populated only for the "unresolved" pseudo-contributor
}

OwnerSummary aggregates tracking data for a single resolved contributor.

type SheetsSource

type SheetsSource struct {
	SheetID         string
	Range           string // e.g. "Sheet1"
	CredentialsFile string // optional override; empty uses gdocs.FindCredentials
}

SheetsSource reads tracking data from a Google Sheets spreadsheet.

func (*SheetsSource) Load

func (s *SheetsSource) Load(ctx context.Context) (*TrackingData, error)

type Source

type Source interface {
	Load(ctx context.Context) (*TrackingData, error)
}

Source loads tracking data from an external system.

func ResolveSource

func ResolveSource(cfg *config.Config) Source

ResolveSource picks the right source from config, returning nil if nothing is configured or available.

type TrackingData

type TrackingData struct {
	Entries   []TrackingEntry
	Source    string // "google_sheets", "csv", "none"
	FetchedAt time.Time
}

TrackingData is the result of loading tracking entries from a source.

func (*TrackingData) ByPath

func (td *TrackingData) ByPath() map[string]*TrackingEntry

ByPath builds a lookup map keyed by normalized path for O(1) merge lookups.

type TrackingEntry

type TrackingEntry struct {
	Path            string
	Status          string // not_started|in_progress|review|done|blocked
	Owner           string
	Notes           string
	PRURL           string
	EstimatedEffort string // trivial|small|medium|large|epic
	UpdatedAt       string
}

TrackingEntry holds a single row of tracking data.