tracking

package
v0.8.0 Latest Latest
Warning

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

Go to latest
Published: Jul 21, 2026 License: MIT Imports: 10 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 (
	// LegacyBundleSchemaVersion is the implicit version used before bundles
	// carried an explicit schema_version field.
	LegacyBundleSchemaVersion = 1
	// CurrentBundleSchemaVersion includes portable evidence provenance.
	CurrentBundleSchemaVersion = 2
)

Variables

This section is empty.

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 accepts legacy unversioned bundles as v1 and rejects unknown schemas before any import writes occur.

Types

type Bundle

type Bundle struct {
	SchemaVersion        int                    `json:"schema_version,omitempty"`
	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.

Jump to

Keyboard shortcuts

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