explore

package
v0.36.0 Latest Latest
Warning

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

Go to latest
Published: Oct 17, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package explore exposes read-only application projections for human-facing exploration surfaces such as the terminal UI.

Index

Constants

View Source
const (
	AttentionPendingApproval  = "pending-approval"
	AttentionChangesRequested = "changes-requested"
	AttentionUnmetDependency  = "unmet-dependency"
	AttentionUnknownContext   = "unknown-context"
)
View Source
const (
	IssueSectionOverview = "overview"
	IssueSectionLinks    = "links"
	IssueSectionActivity = "activity"
)
View Source
const (
	ProjectSectionOverview     = "overview"
	ProjectSectionIssues       = "issues"
	ProjectSectionDependencies = "dependencies"
	ProjectSectionUpgrades     = "upgrades"
	ProjectSectionActivity     = "activity"
)

Variables

View Source
var ErrIssueNotFound = errors.New("issue not found")
View Source
var ErrProjectNotFound = errors.New("project not found")

Functions

This section is empty.

Types

type Activity

type Activity struct {
	ID         int64
	ProjectKey string
	Type       string
	EntityType string
	EntityID   string
	Actor      string
	OccurredAt time.Time
}

Activity is one recent immutable audit event.

type AttentionCounts added in v0.28.0

type AttentionCounts struct {
	Total, Issues, PendingApproval, ChangesRequested, UnmetDependencies, UnknownContext int
}

type AttentionCursor added in v0.28.0

type AttentionCursor struct {
	Number     int
	IssueID    int64
	ReasonRank int
	LinkID     int64
	QueryKey   string
}

AttentionCursor is exclusive and project/order-bound. Pages are live reads.

type AttentionIssue added in v0.28.0

type AttentionIssue struct {
	ID                                int64
	Number                            int
	Key, Type, Title, State, Priority string
	EraID                             int64
	ContractID                        string
	ContractVersion                   int
	Archived, WorkflowKnown, Terminal bool
}

type AttentionItem added in v0.28.0

type AttentionItem struct {
	Source           AttentionIssue
	Target           *AttentionIssue
	TargetID, LinkID int64
	Kind, Reason     string
	ReasonRank       int
}

AttentionItem is a reason occurrence, not a distinct issue or execution gate. TargetID may be recorded while Target is nil, indicating missing context.

type AuditEvent

type AuditEvent struct {
	ID                          int64
	ProjectKey, Type            string
	EntityType, EntityID, Actor string
	Payload                     json.RawMessage
	OccurredAt                  time.Time
}

type AuditPage

type AuditPage struct {
	Events       []AuditEvent
	NextBeforeID int64
}

type AuditQuery

type AuditQuery struct {
	BeforeID  int64
	Limit     int
	Project   string
	Actor     string
	EventType string
	Entity    string
}

type Dashboard

type Dashboard struct {
	Summary        Summary
	Projects       []ProjectSummary
	RecentActivity []Activity
}

Dashboard is the global read model shown when the TUI starts.

type DashboardQuery

type DashboardQuery struct {
	ProjectLimit  int
	ActivityLimit int
}

DashboardQuery bounds the collections returned by LoadDashboard.

type DependencySummary

type DependencySummary struct {
	IssueKey, RequiredIssueKey string
	Resolved                   bool
}

type IssueDetail

type IssueDetail struct {
	Issue    IssueInfo
	Links    []IssueLink
	Activity []Activity
}

type IssueInfo

type IssueInfo struct {
	IssueListItem
	Tracker         *tracker.Link
	Revision        int
	ContractID      string
	ContractVersion int
	Fields          map[string]any
	CreatedAt       time.Time
}
type IssueLink struct {
	Kind, Direction, IssueKey, Label string
	Resolved                         bool
}

type IssueListItem

type IssueListItem struct {
	ID                                             int64
	ProjectID                                      int64
	ProjectKey, ProjectName                        string
	Key, Type, Title, Description, Priority, State string
	ExternalKey                                    string
	Terminal, Historical                           bool
	Effort                                         *int
	UpdatedAt                                      time.Time
}

type IssueListQuery

type IssueListQuery struct {
	IncludeHistory bool
	Limit          int
}

type IssueQuery

type IssueQuery struct {
	Reference string
	Section   string
	Limit     int
}

type IssueRelationship added in v0.24.0

type IssueRelationship struct {
	Kind   string
	Source IssueRelationshipIssue
	Target IssueRelationshipIssue
}

IssueRelationship preserves the stored source-to-target relationship direction and enough endpoint data for list projections and link trays.

type IssueRelationshipIssue added in v0.24.0

type IssueRelationshipIssue struct {
	ID, ProjectID                                 int64
	ProjectKey, Key, Type, Title, Priority, State string
	ExternalKey                                   string
}

IssueRelationshipIssue is a compact endpoint projection used by relationship views; it intentionally excludes descriptions and custom fields.

type IssueRelationshipPage added in v0.24.0

type IssueRelationshipPage struct {
	Items   []IssueRelationship
	HasMore bool
}

IssueRelationshipPage is a bounded relationship projection. HasMore means the returned set is incomplete and must not be presented as authoritative.

type IssueRelationshipQuery added in v0.24.0

type IssueRelationshipQuery struct {
	IssueKeys []string
	Limit     int
}

IssueRelationshipQuery selects direct relationships touching any loaded issue.

type IssueSummary

type IssueSummary struct {
	Key, Type, Title, Priority, State string
	ExternalKey                       string
	Effort                            *int
	UpdatedAt                         time.Time
}

type ProjectAttentionPage added in v0.28.0

type ProjectAttentionPage struct {
	Project ProjectInfo
	Items   []AttentionItem
	Counts  AttentionCounts
	Limit   int
	Next    *AttentionCursor
}

type ProjectAttentionQuery added in v0.28.0

type ProjectAttentionQuery struct {
	Reference string
	After     *AttentionCursor
	Limit     int
}

type ProjectDetail

type ProjectDetail struct {
	Project      ProjectInfo
	Issues       []IssueSummary
	Dependencies []DependencySummary
	Upgrades     []UpgradeSummary
	Activity     []Activity
}

ProjectDetail is the project explorer's read-only aggregate projection.

type ProjectInfo

type ProjectInfo struct {
	ID              int64
	Key             string
	Name            string
	Status          string
	Revision        int
	CreatedAt       time.Time
	EraNumber       int
	ContractID      string
	ContractVersion int
	EraOpenedAt     time.Time
}

type ProjectIssueCatalogPage added in v0.26.0

type ProjectIssueCatalogPage struct {
	Project ProjectInfo
	Issues  []IssueSummary
	Total   int
	Limit   int
	Next    *ProjectIssueCursor
	Filters ProjectIssueFilterOptions
}

type ProjectIssueCatalogQuery added in v0.26.0

type ProjectIssueCatalogQuery struct {
	Reference                   string
	IncludeHistory              bool
	Order                       ProjectIssueOrder
	State, Type, Priority, Text string
	After                       *ProjectIssueCursor
	Limit                       int
}

ProjectIssueCatalogQuery filters the full unarchived project dataset before paging. IncludeHistory includes closed records, preserving project-list scope.

type ProjectIssueCursor added in v0.26.0

type ProjectIssueCursor struct {
	PriorityRank, Number int
	ID                   int64
	QueryKey             string
}

ProjectIssueCursor is exclusive and bound to the project, order and filters. Subsequent pages are live reads, not a snapshot across requests.

type ProjectIssueFilterOptions added in v0.26.0

type ProjectIssueFilterOptions struct {
	States, Types, Priorities []string
	StatesByType              map[string][]string
}

type ProjectIssueOrder added in v0.10.0

type ProjectIssueOrder string

ProjectIssueOrder controls the bounded issue order for a project projection.

const (
	ProjectIssueOrderPriority ProjectIssueOrder = "priority"
	ProjectIssueOrderNewest   ProjectIssueOrder = "newest"
)

type ProjectQuery

type ProjectQuery struct {
	Reference       string
	Section         string
	IncludeHistory  bool
	IssueOrder      ProjectIssueOrder
	IssueLimit      int
	DependencyLimit int
	UpgradeLimit    int
	ActivityLimit   int
}

ProjectQuery bounds the lazily loaded collections in a project detail.

type ProjectSummary

type ProjectSummary struct {
	ID                  int64
	Key                 string
	Name                string
	ContractID          string
	ContractVersion     int
	ActiveIssues        int
	TerminalIssues      int
	PendingDependencies int
	LastActivity        time.Time
}

ProjectSummary is one active project row ordered by recent activity.

type ProjectTokensPage added in v0.29.0

type ProjectTokensPage struct {
	Project        ProjectInfo
	Items          []TokenMetadata
	Total, Pending int
	Next           *TokenCursor
}

type ProjectTokensQuery added in v0.29.0

type ProjectTokensQuery struct {
	Reference string
	After     *TokenCursor
	Limit     int
}

type SearchQuery

type SearchQuery struct {
	Text  string
	Limit int
}

type SearchResult

type SearchResult struct {
	EntityType, Key, ProjectKey, Type, Label, Context, MatchedField, Snippet string
	Historical                                                               bool
}

type Store

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

Store owns non-mutating exploration queries over an existing database.

func Open

func Open(ctx context.Context, path string) (*Store, error)

Open opens an existing fully migrated database without changing it.

func (*Store) Close

func (s *Store) Close() error

Close releases the database connection.

func (*Store) ListIssueRelationships added in v0.24.0

func (s *Store) ListIssueRelationships(ctx context.Context, query IssueRelationshipQuery) (IssueRelationshipPage, error)

ListIssueRelationships returns direct links touching any supplied issue key in one bounded query. It does not recursively load neighbors.

func (*Store) ListIssues

func (s *Store) ListIssues(ctx context.Context, query IssueListQuery) ([]IssueListItem, error)

ListIssues returns recent cross-project work, optionally including history.

func (*Store) LoadAudit

func (s *Store) LoadAudit(ctx context.Context, query AuditQuery) (AuditPage, error)

LoadAudit returns one reverse-chronological cursor page with exact contextual filters.

func (*Store) LoadDashboard

func (s *Store) LoadDashboard(ctx context.Context, query DashboardQuery) (Dashboard, error)

LoadDashboard returns bounded global summary, project, and activity views.

func (*Store) LoadIssue

func (s *Store) LoadIssue(ctx context.Context, query IssueQuery) (IssueDetail, error)

LoadIssue lazily loads one issue section.

func (*Store) LoadProject

func (s *Store) LoadProject(ctx context.Context, query ProjectQuery) (ProjectDetail, error)

LoadProject lazily loads one project and the bounded collections used by its tabs.

func (*Store) LoadProjectAttention added in v0.28.0

func (s *Store) LoadProjectAttention(ctx context.Context, q ProjectAttentionQuery) (ProjectAttentionPage, error)

func (*Store) LoadProjectIssueCatalog added in v0.26.0

func (s *Store) LoadProjectIssueCatalog(ctx context.Context, q ProjectIssueCatalogQuery) (ProjectIssueCatalogPage, error)

LoadProjectIssueCatalog reads a bounded page and matched total from the same transaction. Priority is resolved using each record's persisted era contract.

func (*Store) LoadProjectTokens added in v0.29.0

func (s *Store) LoadProjectTokens(ctx context.Context, q ProjectTokensQuery) (ProjectTokensPage, error)

LoadProjectTokens reads only metadata in a single read-only transaction. It never opens credential storage, decrypts a value or creates credential files.

func (*Store) Search

func (s *Store) Search(ctx context.Context, query SearchQuery) ([]SearchResult, error)

Search finds projects and issues using only canonical human-facing fields.

type Summary

type Summary struct {
	ActiveProjects      int
	ActiveIssues        int
	TerminalIssues      int
	PendingDependencies int
	OpenUpgradePlans    int
}

Summary contains structural metrics that are comparable across contracts.

type TokenCursor added in v0.29.0

type TokenCursor struct {
	ProjectID  int64
	Identifier string
}

type TokenMetadata added in v0.29.0

type TokenMetadata struct {
	Identifier, Status     string
	Revision               int
	ExpiresAt, RequestedAt *time.Time
	UpdatedAt              time.Time
}

TokenMetadata deliberately has no credential, ciphertext, key or file path.

type UpgradeSummary

type UpgradeSummary struct {
	ID                     int64
	FromVersion, ToVersion int
	Status, CreatedBy      string
	CreatedAt              time.Time
}

Jump to

Keyboard shortcuts

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