research

package
v0.14.0 Latest Latest
Warning

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

 Go to latest Published: Jul 29, 2026 License: MIT Imports: 17 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,omitempty"`
	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
	MergedKnown       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.