radar

package

v0.13.0 Latest Latest Go to latest Published: Jul 28, 2026 License: MIT Imports: 8 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/morluto/gitcontribute

Links

Open Source Insights

Documentation ¶

Overview ¶

Package radar ranks locally stored contribution candidates with transparent, deterministic signals. It performs no I/O and owns no GitHub capability.

Constants ¶

View Source

const (
	// ScoreVersion changes whenever ranking semantics change.
	ScoreVersion = "radar.v3"
	// DefaultLimit is the default number of returned candidates.
	DefaultLimit = 20
	// MaxLimit bounds one radar response.
	MaxLimit = 500
)

Variables ¶

This section is empty.

Functions ¶

This section is empty.

Types ¶

type Candidate ¶

type Candidate struct {
	Rank               int                 `json:"rank"`
	Ref                string              `json:"ref"`
	Repo               string              `json:"repo"`
	Number             int                 `json:"number"`
	Title              string              `json:"title"`
	URL                string              `json:"url"`
	Labels             []string            `json:"labels"`
	Eligibility        Eligibility         `json:"eligibility"`
	BaseScore          int                 `json:"base_score"`
	Score              int                 `json:"score"`
	ScoreVersion       string              `json:"score_version"`
	Confidence         string              `json:"confidence"`
	PositiveSignals    []Signal            `json:"positive_signals"`
	Risks              []Signal            `json:"risks"`
	Blockers           []Signal            `json:"blockers"`
	Unknowns           []Unknown           `json:"unknowns"`
	Coverage           []Coverage          `json:"coverage"`
	LinkedPullRequests []LinkedPullRequest `json:"linked_pull_requests"`
	RelatedWork        []RelatedWork       `json:"related_work"`
	DuplicateCluster   *DuplicateCluster   `json:"duplicate_cluster,omitempty"`
	SourceUpdatedAt    time.Time           `json:"source_updated_at,omitempty"`
	SourceAsOf         time.Time           `json:"source_as_of,omitempty"`
}

Candidate is one ranked, fully explained issue.

type Coverage ¶

type Coverage struct {
	Facet    string    `json:"facet"`
	Scope    string    `json:"scope"`
	Present  bool      `json:"present"`
	Complete bool      `json:"complete"`
	AsOf     time.Time `json:"as_of,omitempty"`
}

Coverage is the bounded facet coverage relevant to a recommendation.

type DiscussionComment ¶ added in v0.8.0

type DiscussionComment struct {
	Author            string
	AuthorAssociation string
	Body              string
	URL               string
	CreatedAt         time.Time
}

DiscussionComment is the product-owned discussion evidence consumed by the pure eligibility classifier.

type DiscussionSummary ¶ added in v0.8.0

type DiscussionSummary struct {
	MaintainerResponseURL  string
	MaintainerDirection    string
	MaintainerDirectionURL string
	ActiveClaimAuthors     []string
	ActiveClaimURL         string
}

DiscussionSummary is the bounded, source-backed eligibility evidence extracted from a complete stored comment snapshot.

func SummarizeDiscussion ¶ added in v0.8.0

func SummarizeDiscussion(comments []DiscussionComment, now time.Time) DiscussionSummary

SummarizeDiscussion classifies a complete stored comment snapshot into the compact facts needed by contribution eligibility. It performs no I/O.

type DuplicateCluster ¶

type DuplicateCluster struct {
	StableID       string    `json:"stable_id"`
	CanonicalRef   string    `json:"canonical_ref"`
	CandidateCount int       `json:"candidate_count"`
	SourceAsOf     time.Time `json:"source_as_of,omitempty"`
}

DuplicateCluster is a stored, explainable duplicate-candidate fact.

type Eligibility ¶

type Eligibility string

Eligibility separates objective state from a candidate's numeric score.

const (
	// EligibilityReadyToCode means source-backed policy, ownership, discussion,
	// and issue evidence contain no reason to delay implementation.
	EligibilityReadyToCode Eligibility = "ready_to_code"
	// EligibilityNeedsDiagnosis means the problem or requested behavior still
	// needs reproduction, triage, or acceptance clarification.
	EligibilityNeedsDiagnosis Eligibility = "needs_diagnosis"
	// EligibilityNeedsCoordination means a contributor should coordinate with
	// maintainers or another participant before starting implementation.
	EligibilityNeedsCoordination Eligibility = "needs_coordination"
	// EligibilityBlocked means stored evidence contains an objective blocker.
	EligibilityBlocked Eligibility = "blocked"
)

type GuidanceDocument ¶ added in v0.8.0

type GuidanceDocument struct {
	Path    string
	Content string
	URL     string
}

GuidanceDocument is one source-backed repository policy document.

type IssueSnapshot ¶

type IssueSnapshot struct {
	Number             int
	State              string
	Title              string
	Body               string
	Labels             []string
	Assignees          []string
	Locked             bool
	SourceUpdated      time.Time
	URL                string
	Coverage           []Coverage
	Discussion         DiscussionSummary
	LinkedPullRequests []LinkedPullRequest
	RelatedWork        []RelatedWork
	RelatedWorkCapped  bool
	DuplicateCluster   *DuplicateCluster
}

IssueSnapshot contains one locally stored issue and its derived local facts.

type LinkedPullRequest ¶

type LinkedPullRequest struct {
	Number          int       `json:"number"`
	Title           string    `json:"title"`
	URL             string    `json:"url"`
	Closing         bool      `json:"closing"`
	SourceUpdatedAt time.Time `json:"source_updated_at,omitempty"`
}

LinkedPullRequest is an open PR that explicitly references an issue.

type Options ¶

type Options struct {
	Limit                       int
	Now                         time.Time
	TotalOpenIssues             int
	PopulationCapped            bool
	LinkedPullRequestScanCapped bool
	DuplicateClusterScanCapped  bool
}

Options bounds a deterministic ranking operation.

type RelatedWork ¶ added in v0.8.0

type RelatedWork struct {
	Ref             string                `json:"ref"`
	Kind            string                `json:"kind"`
	Number          int                   `json:"number,omitempty"`
	Title           string                `json:"title,omitempty"`
	State           string                `json:"state,omitempty"`
	Relation        string                `json:"relation"`
	Direction       string                `json:"direction,omitempty"`
	URL             string                `json:"url,omitempty"`
	Evidence        []RelatedWorkEvidence `json:"evidence"`
	SourceUpdatedAt time.Time             `json:"source_updated_at,omitempty"`
}

RelatedWork is one normalized issue, pull request, or local cluster related to a candidate. Relation is the strongest stored relationship; Evidence preserves every distinct source that contributed to that conclusion.

type RelatedWorkEvidence ¶ added in v0.8.0

type RelatedWorkEvidence struct {
	Kind       string    `json:"kind"`
	SourceURL  string    `json:"source_url"`
	SourceAsOf time.Time `json:"source_as_of,omitempty"`
}

RelatedWorkEvidence identifies one stored source supporting a relationship.

type Report ¶

type Report struct {
	Repo                string      `json:"repo"`
	ScoreVersion        string      `json:"score_version"`
	GeneratedAt         time.Time   `json:"generated_at"`
	SourceAsOf          time.Time   `json:"source_as_of,omitempty"`
	Limit               int         `json:"limit"`
	TotalOpenIssues     int         `json:"total_open_issues"`
	CandidatePopulation int         `json:"candidate_population"`
	PopulationCapped    bool        `json:"population_capped"`
	Unknowns            []Unknown   `json:"unknowns"`
	Candidates          []Candidate `json:"candidates"`
}

Report is the offline contribution radar result for one repository.

func Rank ¶

func Rank(repo RepositorySnapshot, issues []IssueSnapshot, opts Options) (*Report, error)

Rank scores a bounded set of local issue snapshots. Missing coverage is represented as unknown and never silently converted into a penalty.

type RepositorySnapshot ¶

type RepositorySnapshot struct {
	Repo           domain.RepoRef
	Archived       bool
	SourceUpdated  time.Time
	Coverage       []Coverage
	GuidanceStatus string
	Guidance       []GuidanceDocument
}

RepositorySnapshot contains only product-owned facts required by Rank.

type Signal ¶

type Signal struct {
	Code      string `json:"code"`
	Summary   string `json:"summary"`
	Weight    int    `json:"weight"`
	SourceURL string `json:"source_url,omitempty"`
}

Signal is one explainable contribution to a candidate assessment.

type Unknown ¶

type Unknown struct {
	Code        string `json:"code"`
	Summary     string `json:"summary"`
	Remediation string `json:"remediation,omitempty"`
}

Unknown records missing or incomplete evidence without treating it as a negative ranking signal.

Source Files ¶

View all Source files

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