Help us shape the future of Go! Take the 2026 Go Developer Survey

research

package
v0.3.0 Latest Latest
Warning

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

 Go to latest Published: Jul 18, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package research builds deterministic, source-backed thread research briefs. It owns no network, persistence, process, or GitHub mutation capability.

Index

Constants

View Source 
const (
	// SchemaVersion changes whenever the portable brief contract changes.
	SchemaVersion = "research-brief.v1"
	// MaximumBodyExcerpt bounds untrusted source text in one brief.
	MaximumBodyExcerpt = 2000
)

Variables

View Source 
var (
	// ErrThreadNotFound distinguishes a missing local projection from missing
	// child coverage.
	ErrThreadNotFound = errors.New("research thread not found")
	// ErrThreadKindMismatch reports an explicit issue:/pr: ref that disagrees
	// with the stored projection.
	ErrThreadKindMismatch = errors.New("research thread kind mismatch")
)

Functions

func KindMismatchError 

func KindMismatchError(requested, stored domain.ThreadKind) error

KindMismatchError preserves the requested and stored kinds.

func RenderMarkdown 

func RenderMarkdown(w io.Writer, brief *Brief) error

RenderMarkdown writes a deterministic, redacted research brief. Untrusted source excerpts are quoted and HTML-escaped so they remain data.

Types

type AcceptanceSection 

type AcceptanceSection struct {
	SectionMeta
	Checklist            []ChecklistHint `json:"checklist"`
	RelevantHeadings     []TextHint      `json:"relevant_headings"`
	MaintainerStatements []TextHint      `json:"maintainer_statements"`
	Caveat               string          `json:"caveat"`
}

AcceptanceSection contains extracted hints with an explicit caveat.

type Brief 

type Brief struct {
	SchemaVersion string    `json:"schema_version"`
	GeneratedAt   time.Time `json:"generated_at"`
	SourceAsOf    time.Time `json:"source_as_of"`
	Target        Target    `json:"target"`
	Sections      Sections  `json:"sections"`
}

Brief is a deterministic human/agent research package.

func (*Brief) ValidateProvenance 

func (b *Brief) ValidateProvenance() error

ValidateProvenance verifies the core contract for all fixed sections.

type Builder 

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

Builder assembles a research brief from already stored, source-backed facts.

func NewBuilder 

func NewBuilder(reader Reader, clock func() time.Time) *Builder

NewBuilder returns a deterministic research brief builder.

func (*Builder) Build 

func (b *Builder) Build(ctx context.Context, requested ThreadRef) (*Brief, error)

Build reads only the capabilities exposed by Reader and produces a fixed v1 brief. Source content is treated as data, never as instructions.

type ChecklistHint 

type ChecklistHint struct {
	Text    string    `json:"text"`
	Checked bool      `json:"checked"`
	Source  SourceRef `json:"source"`
}

ChecklistHint is one source checkbox, not a claim of complete acceptance.

type CodeEvidence 

type CodeEvidence struct {
	Present   bool
	CommitSHA string
	Queries   []string
	Hits      []CodeHit
	Source    SourceRef
	Truncated bool
}

CodeEvidence reports the latest immutable snapshot and bounded matches.

type CodeHit 

type CodeHit struct {
	Path        string    `json:"path"`
	Language    string    `json:"language,omitempty"`
	CommitSHA   string    `json:"commit_sha"`
	MatchedTerm string    `json:"matched_term"`
	Source      SourceRef `json:"source"`
}

CodeHit is one path-level match at an immutable indexed commit.

type CodeReader 

type CodeReader interface {
	ReadResearchCode(ctx context.Context, repo domain.RepoRef, terms []string) (CodeEvidence, error)
}

CodeReader searches only an already indexed local snapshot.

type CodeSection 

type CodeSection struct {
	SectionMeta
	CommitSHA string    `json:"commit_sha,omitempty"`
	Queries   []string  `json:"queries"`
	Hits      []CodeHit `json:"hits"`
	Truncated bool      `json:"truncated"`
}

CodeSection contains bounded local-index hits.

type CoverageFact 

type CoverageFact struct {
	Scope     string    `json:"scope"`
	Facet     string    `json:"facet"`
	Present   bool      `json:"present"`
	Complete  bool      `json:"complete"`
	Truncated bool      `json:"truncated"`
	AsOf      time.Time `json:"as_of,omitempty"`
	Count     int       `json:"count"`
}

CoverageFact records one repository, thread, or local-index coverage fact.

type CoverageSection 

type CoverageSection struct {
	SectionMeta
	Facets []CoverageFact `json:"facets"`
	Gaps   []string       `json:"gaps"`
}

CoverageSection makes missing and partial inputs inspectable.

type CurrentStateSection 

type CurrentStateSection struct {
	SectionMeta
	State       string    `json:"state"`
	StateReason string    `json:"state_reason,omitempty"`
	Draft       bool      `json:"draft"`
	Locked      bool      `json:"locked"`
	Merged      bool      `json:"merged"`
	Labels      []string  `json:"labels"`
	Milestone   string    `json:"milestone,omitempty"`
	CreatedAt   time.Time `json:"created_at,omitempty"`
	UpdatedAt   time.Time `json:"updated_at,omitempty"`
	ClosedAt    time.Time `json:"closed_at,omitempty"`
	MergedAt    time.Time `json:"merged_at,omitempty"`
}

CurrentStateSection records lifecycle facts without inference.

type DiscussionItem 

type DiscussionItem struct {
	ID                int64
	Kind              string
	Body              string
	Author            string
	AuthorAssociation string
	State             string
	Path              string
	CreatedAt         time.Time
	UpdatedAt         time.Time
	Source            SourceRef
}

DiscussionItem is one stored comment, review, or review comment.

type DuplicateSection 

type DuplicateSection struct {
	SectionMeta
	ClusterID  string          `json:"cluster_id,omitempty"`
	Canonical  string          `json:"canonical,omitempty"`
	Candidates []RelatedThread `json:"candidates"`
	Truncated  bool            `json:"truncated"`
	Caveat     string          `json:"caveat"`
}

DuplicateSection separates candidates from confirmed duplicate decisions.

type FacetCoverage 

type FacetCoverage struct {
	Facet     string
	Present   bool
	Complete  bool
	Truncated bool
	AsOf      time.Time
	Count     int
	Source    SourceRef
}

FacetCoverage describes one thread child-facet snapshot.

type GuidanceSection 

type GuidanceSection struct {
	SectionMeta
	Text string `json:"text,omitempty"`
}

GuidanceSection never invents contribution or AI policy.

type HealthEvidence 

type HealthEvidence struct {
	Available                      bool
	Archived                       bool
	OpenIssues                     int
	OpenPullRequests               int
	ExternalPRMergeRate            float64
	ExternalPRSampleSize           int
	IssueResponseMedianHours       float64
	PullRequestResponseMedianHours float64
	IssueResponseSampleSize        int
	PullRequestResponseSampleSize  int
	ThreadSampleSize               int
	ThreadsTruncated               bool
	Sources                        []SourceRef
	UnknownReason                  string
}

HealthEvidence is a compact adapter view over offline health metrics.

type HealthReader 

type HealthReader interface {
	ReadResearchHealth(ctx context.Context, repo domain.RepoRef) (HealthEvidence, error)
}

HealthReader returns existing offline health metrics.

type HealthSection 

type HealthSection struct {
	SectionMeta
	Archived                       bool    `json:"archived"`
	OpenIssues                     int     `json:"open_issues"`
	OpenPullRequests               int     `json:"open_pull_requests"`
	ExternalPRMergeRate            float64 `json:"external_pr_merge_rate"`
	ExternalPRSampleSize           int     `json:"external_pr_sample_size"`
	IssueResponseMedianHours       float64 `json:"issue_response_median_hours"`
	PullRequestResponseMedianHours float64 `json:"pull_request_response_median_hours"`
	IssueResponseSampleSize        int     `json:"issue_response_sample_size"`
	PullRequestResponseSampleSize  int     `json:"pull_request_response_sample_size"`
	ThreadSampleSize               int     `json:"thread_sample_size"`
	ThreadsTruncated               bool    `json:"threads_truncated"`
}

HealthSection is a compact projection of existing offline metrics.

type NextCommand 

type NextCommand struct {
	Reason  string `json:"reason"`
	Command string `json:"command"`
}

NextCommand is a copyable, explicit remediation or follow-on read.

type NextSection 

type NextSection struct {
	SectionMeta
	Commands []NextCommand `json:"commands"`
}

NextSection provides deterministic follow-up commands only.

type Participant 

type Participant struct {
	Login       string   `json:"login"`
	Association string   `json:"association,omitempty"`
	Roles       []string `json:"roles"`
}

Participant records public association and observed roles.

type ParticipantsSection 

type ParticipantsSection struct {
	SectionMeta
	Participants []Participant `json:"participants"`
}

ParticipantsSection reports only identities present in stored evidence.

type ProblemSection 

type ProblemSection struct {
	SectionMeta
	Title       string   `json:"title"`
	BodyExcerpt string   `json:"body_excerpt,omitempty"`
	Labels      []string `json:"labels"`
	Assignees   []string `json:"assignees"`
}

ProblemSection exposes only stored fields and a bounded verbatim excerpt.

type PullRequestSection 

type PullRequestSection struct {
	SectionMeta
	PullRequests []RelatedThread `json:"pull_requests"`
	Truncated    bool            `json:"truncated"`
}

PullRequestSection reports open PRs that mention or claim to close a target.

type Reader 

type Reader interface {
	repository.Reader
	ThreadReader
	RelationshipReader
	CodeReader
	HealthReader
}

Reader is the composed, product-owned source contract for a brief. Each embedded capability remains independently testable and side-effect bounded.

type Reference 

type Reference struct {
	Repo   domain.RepoRef
	Kind   domain.ThreadKind
	Number int
	Source SourceRef
}

Reference is an explicit source-text reference before corpus resolution.

type RelatedThread 

type RelatedThread struct {
	Ref      string    `json:"ref"`
	Kind     string    `json:"kind,omitempty"`
	Number   int       `json:"number"`
	Title    string    `json:"title,omitempty"`
	State    string    `json:"state,omitempty"`
	Relation string    `json:"relation"`
	Basis    string    `json:"basis"`
	URL      string    `json:"url"`
	Source   SourceRef `json:"source"`
}

RelatedThread is a source-backed explicit or clustered relationship.

type RelationshipEvidence 

type RelationshipEvidence struct {
	ClusterID         string
	Canonical         string
	DuplicateThreads  []RelatedThread
	PullRequests      []RelatedThread
	Sources           []SourceRef
	DuplicateCapped   bool
	PullRequestCapped bool
}

RelationshipEvidence contains locally resolved explicit, cluster, and PR relationships. Absence is meaningful only when Sources is non-empty and the corresponding scan is not truncated.

type RelationshipReader 

type RelationshipReader interface {
	ReadResearchRelationships(ctx context.Context, ref ThreadRef, explicit []Reference) (RelationshipEvidence, error)
}

RelationshipReader performs bounded local relationship lookups.

type SectionMeta 

type SectionMeta struct {
	Status        SectionStatus `json:"status"`
	Sources       []SourceRef   `json:"sources"`
	UnknownReason string        `json:"unknown_reason,omitempty"`
}

SectionMeta is embedded in every brief section.

type SectionStatus 

type SectionStatus string

SectionStatus makes missing or incomplete evidence explicit. 

const (
	// StatusAvailable means the section is backed by complete stored evidence.
	StatusAvailable SectionStatus = "available"
	// StatusPartial means some expected stored evidence is incomplete or capped.
	StatusPartial SectionStatus = "partial"
	// StatusUnknown means the corpus cannot support a claim for the section.
	StatusUnknown SectionStatus = "unknown"
)

type Sections 

type Sections struct {
	CurrentState CurrentStateSection `json:"current_state"`
	Problem      ProblemSection      `json:"problem_statement"`
	Acceptance   AcceptanceSection   `json:"acceptance_hints"`
	Participants ParticipantsSection `json:"participants"`
	Timeline     TimelineSection     `json:"timeline"`
	Duplicates   DuplicateSection    `json:"duplicate_candidates"`
	PullRequests PullRequestSection  `json:"linked_pull_requests"`
	Code         CodeSection         `json:"relevant_code"`
	Guidance     GuidanceSection     `json:"contribution_guidance"`
	Health       HealthSection       `json:"repository_health"`
	Coverage     CoverageSection     `json:"coverage_and_gaps"`
	Next         NextSection         `json:"next_commands"`
}

Sections is the fixed v1 research brief contract.

type SourceRef 

type SourceRef struct {
	Source     string    `json:"source"`
	URL        string    `json:"url,omitempty"`
	CommitSHA  string    `json:"commit_sha,omitempty"`
	ObservedAt time.Time `json:"observed_at,omitempty"`
	AsOf       time.Time `json:"as_of,omitempty"`
}

SourceRef is the JSON-stable provenance representation used by briefs.

type Target 

type Target struct {
	Ref        string `json:"ref"`
	Repository string `json:"repository"`
	Kind       string `json:"kind"`
	Number     int    `json:"number"`
	URL        string `json:"url"`
}

Target identifies the resolved source thread.

type TextHint 

type TextHint struct {
	Text   string    `json:"text"`
	Author string    `json:"author,omitempty"`
	Source SourceRef `json:"source"`
}

TextHint is a source heading or maintainer statement.

type ThreadEvidence 

type ThreadEvidence struct {
	Thread     ThreadSnapshot
	Discussion []DiscussionItem
	Coverage   []FacetCoverage
	Truncated  bool
}

ThreadEvidence includes bounded child data and explicit coverage facts.

type ThreadReader 

type ThreadReader interface {
	ReadResearchThread(ctx context.Context, ref ThreadRef) (ThreadEvidence, error)
}

ThreadReader reads one thread and its already stored child facets.

type ThreadRef 

type ThreadRef struct {
	Repo   domain.RepoRef
	Kind   domain.ThreadKind
	Number int
}

ThreadRef is a validated issue or pull-request reference. Kind may be empty when the input used OWNER/REPO#NUMBER and the corpus must resolve it.

func ParseThreadRef 

func ParseThreadRef(raw string) (ThreadRef, error)

ParseThreadRef accepts OWNER/REPO#NUMBER and the explicit issue:, pr:, or pull_request: forms.

func (ThreadRef) String 

func (r ThreadRef) String() string

String returns the explicit, stable form when kind is known.

func (ThreadRef) Validate 

func (r ThreadRef) Validate() error

Validate checks a programmatically constructed thread reference.

type ThreadSnapshot 

type ThreadSnapshot struct {
	Ref               ThreadRef
	Title             string
	Body              string
	Author            string
	AuthorAssociation string
	State             string
	StateReason       string
	Labels            []string
	Assignees         []string
	Draft             bool
	Locked            bool
	Milestone         string
	Merged            bool
	CreatedAt         time.Time
	UpdatedAt         time.Time
	ClosedAt          time.Time
	MergedAt          time.Time
	Source            SourceRef
}

ThreadSnapshot is a product-owned issue/PR projection.

type TimelineEvent 

type TimelineEvent struct {
	At      time.Time `json:"at"`
	Kind    string    `json:"kind"`
	Actor   string    `json:"actor,omitempty"`
	Summary string    `json:"summary"`
	Source  SourceRef `json:"source"`
}

TimelineEvent is one bounded source event.

type TimelineSection 

type TimelineSection struct {
	SectionMeta
	Events    []TimelineEvent `json:"events"`
	Truncated bool            `json:"truncated"`
}

TimelineSection is deterministically ordered by time and stable identity.

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.