tracking

package
v1.1.0 Latest Latest
Warning

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

 Go to latest Published: Aug 8, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package tracking models local contribution research history.

Triage decisions, prepared contributions, and outcomes are validated before persistence and can be exported deterministically. Export sanitization redacts credentials and absolute local paths; it is a publication boundary, not a substitute for avoiding secrets in source records.

Index

Constants

View Source 
const (
	// CurrentBundleSchemaVersion includes portable evidence provenance.
	CurrentBundleSchemaVersion = 2
)

Variables

View Source 
var ErrExportTruncated = errors.New("tracking export would be incomplete")

ErrExportTruncated indicates that a requested bundle limit cannot contain a complete portable snapshot.

View Source 
var ErrImportConflict = errors.New("tracking import conflict")

ErrImportConflict reports two different immutable or equal-timestamp revisions carrying the same durable ID.

Functions

func OrderBundle 

func OrderBundle(bundle *Bundle)

OrderBundle sorts each slice so the same records produce the same JSON.

func ResolveBundleVersion 

func ResolveBundleVersion(bundle *Bundle) (int, error)

ResolveBundleVersion rejects any bundle that does not declare the current schema before import writes occur.

Types

type Bundle 

type Bundle struct {
	SchemaVersion        int                    `json:"schema_version"`
	TriageEvents         []*TriageEvent         `json:"triage_events"`
	Contributions        []*Contribution        `json:"contributions"`
	ContributionOutcomes []*ContributionOutcome `json:"contribution_outcomes"`
	Evidence             []*evidence.Evidence   `json:"evidence,omitempty"`
}

Bundle is a portable, deterministic snapshot of local tracking metadata.

func SanitizeBundle 

func SanitizeBundle(bundle *Bundle) *Bundle

SanitizeBundle returns a deep copy of bundle with secrets, credentials, and absolute local paths redacted.

type Contribution 

type Contribution struct {
	ID            string
	OpportunityID string
	Kind          string
	Title         string
	Body          string
	Reference     string
	ReferenceURL  string
	PreparedAt    time.Time
	SubmittedAt   *time.Time
	CreatedAt     time.Time
	UpdatedAt     time.Time
	Metadata      map[string]any
}

Contribution records prepared or submitted contribution material for an opportunity, kept separate from the live GitHub state.

type ContributionFilter 

type ContributionFilter struct {
	OpportunityID string
	Kind          string
	Limit         int
}

ContributionFilter bounds the contributions returned by a query.

type ContributionOutcome 

type ContributionOutcome struct {
	ID             string
	ContributionID string
	Outcome        Outcome
	Reason         string
	SourceEventAt  time.Time
	CreatedAt      time.Time
}

ContributionOutcome records a lifecycle event for a contribution.

type ExportOptions 

type ExportOptions struct {
	Limit int
}

ExportOptions bounds a local metadata export.

type Outcome 

type Outcome string

Outcome records a local triage or lifecycle decision. 

const (
	OutcomeViewed       Outcome = "viewed"
	OutcomeIgnored      Outcome = "ignored"
	OutcomeSaved        Outcome = "saved"
	OutcomeInvestigated Outcome = "investigated"
	OutcomeImplemented  Outcome = "implemented"
	OutcomeSubmitted    Outcome = "submitted"
	OutcomeMerged       Outcome = "merged"
	OutcomeRejected     Outcome = "rejected"
	OutcomeAbandoned    Outcome = "abandoned"
)

type Repository 

type Repository interface {
	RecordTriageEvent(ctx context.Context, e *TriageEvent) error
	ListTriageEvents(ctx context.Context, filter TriageEventFilter) ([]*TriageEvent, error)

	SaveContribution(ctx context.Context, c *Contribution) error
	GetContribution(ctx context.Context, id string) (*Contribution, error)
	ListContributions(ctx context.Context, filter ContributionFilter) ([]*Contribution, error)

	RecordContributionOutcome(ctx context.Context, o *ContributionOutcome) error
	ListContributionOutcomes(ctx context.Context, contributionID string) ([]*ContributionOutcome, error)

	ExportLocalMetadata(ctx context.Context, opts ExportOptions) (*Bundle, error)
	ImportLocalMetadata(ctx context.Context, bundle *Bundle) error
}

Repository is the persistence boundary for local tracking and feedback.

type Service 

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

Service validates and records local triage decisions and contribution outcomes.

func NewService 

func NewService(repo Repository) *Service

NewService returns a tracking service backed by repo.

func (*Service) ExportLocalMetadata 

func (s *Service) ExportLocalMetadata(ctx context.Context, opts ExportOptions) (*Bundle, error)

ExportLocalMetadata returns a redacted, deterministic bundle of local metadata.

func (*Service) GetContribution 

func (s *Service) GetContribution(ctx context.Context, id string) (*Contribution, error)

GetContribution returns a contribution by durable id.

func (*Service) ImportLocalMetadata 

func (s *Service) ImportLocalMetadata(ctx context.Context, bundle *Bundle) error

ImportLocalMetadata imports a bounded bundle idempotently.

func (*Service) ListContributionOutcomes 

func (s *Service) ListContributionOutcomes(ctx context.Context, contributionID string) ([]*ContributionOutcome, error)

ListContributionOutcomes returns outcomes for a contribution.

func (*Service) ListContributions 

func (s *Service) ListContributions(ctx context.Context, filter ContributionFilter) ([]*Contribution, error)

ListContributions returns contributions ordered by creation time.

func (*Service) ListTriageEvents 

func (s *Service) ListTriageEvents(ctx context.Context, filter TriageEventFilter) ([]*TriageEvent, error)

ListTriageEvents returns triage events ordered by source event time and id.

func (*Service) RecordContribution 

func (s *Service) RecordContribution(ctx context.Context, c *Contribution) (*Contribution, error)

RecordContribution stores prepared or submitted contribution metadata.

func (*Service) RecordContributionOutcome 

func (s *Service) RecordContributionOutcome(ctx context.Context, o *ContributionOutcome) (*ContributionOutcome, error)

RecordContributionOutcome stores a lifecycle event for a contribution.

func (*Service) RecordTriageEvent 

func (s *Service) RecordTriageEvent(ctx context.Context, e *TriageEvent) (*TriageEvent, error)

RecordTriageEvent stores a local triage decision after validating it.

func (*Service) SetClock 

func (s *Service) SetClock(clock func() time.Time)

SetClock overrides the time source. It is intended for tests.

type TargetKind 

type TargetKind string

TargetKind names the kinds of local corpus references that can be tracked. 

const (
	TargetRepository    TargetKind = "repository"
	TargetIssue         TargetKind = "issue"
	TargetPullRequest   TargetKind = "pull_request"
	TargetThread        TargetKind = "thread"
	TargetOpportunity   TargetKind = "opportunity"
	TargetInvestigation TargetKind = "investigation"
)

type TriageEvent 

type TriageEvent struct {
	ID              string
	TargetKind      TargetKind
	TargetRef       string
	Outcome         Outcome
	Reason          string
	Lens            string
	SourceEventAt   time.Time
	RepositoryID    *int64
	ThreadID        *int64
	InvestigationID string
	OpportunityID   string
	CreatedAt       time.Time
	UpdatedAt       time.Time
}

TriageEvent records a single local triage decision for a typed target.

type TriageEventFilter 

type TriageEventFilter struct {
	TargetKind TargetKind
	TargetRef  string
	Outcome    Outcome
	Lens       string
	Limit      int
}

TriageEventFilter bounds the triage events returned by a query.

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.