format

package
v1.6.1 Latest Latest
Warning

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

 Go to latest Published: Feb 26, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package format provides ASCII and JSON formatting for Linear resources. This is a token-efficient alternative to Markdown templates.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AttachmentDTO added in v1.3.0 

type AttachmentDTO struct {
	ID         string `json:"id"`
	Title      string `json:"title"`
	URL        string `json:"url"`
	Subtitle   string `json:"subtitle,omitempty"`
	SourceType string `json:"sourceType"`
	CreatedAt  string `json:"createdAt"`
}

AttachmentDTO represents an attachment

func AttachmentToDTO added in v1.5.0 

func AttachmentToDTO(att *core.Attachment) AttachmentDTO

AttachmentToDTO converts an attachment to DTO

type CommentDTO added in v1.3.0 

type CommentDTO struct {
	ID        string         `json:"id"`
	Body      string         `json:"body"`
	User      *UserDTO       `json:"user"`
	Issue     *IssueRefDTO   `json:"issue"`
	Parent    *CommentRefDTO `json:"parent"`
	CreatedAt string         `json:"createdAt"`
	UpdatedAt string         `json:"updatedAt"`
}

CommentDTO represents a comment in JSON format

func CommentToDTO added in v1.3.0 

func CommentToDTO(comment *core.Comment) CommentDTO

CommentToDTO converts a comment to DTO

type CommentRefDTO added in v1.3.0 

type CommentRefDTO struct {
	ID string `json:"id"`
}

CommentRefDTO is a minimal comment reference

type CommentSummaryDTO added in v1.5.0 

type CommentSummaryDTO struct {
	ID        string   `json:"id"`
	Body      string   `json:"body"`
	User      *UserDTO `json:"user"`
	CreatedAt string   `json:"createdAt"`
}

CommentSummaryDTO is a comment with a truncated body for the detailed view

type CycleCompactDTO added in v1.3.0 

type CycleCompactDTO struct {
	Number   int     `json:"number"`
	Name     string  `json:"name"`
	Status   string  `json:"status"`
	StartsAt string  `json:"startsAt"`
	EndsAt   string  `json:"endsAt"`
	Progress float64 `json:"progress"`
	TeamName *string `json:"teamName"`
}

CycleCompactDTO contains key cycle metadata

func CycleToCompactDTO added in v1.3.0 

func CycleToCompactDTO(cycle *core.Cycle) CycleCompactDTO

CycleToCompactDTO converts a cycle to compact DTO

type CycleFullDTO added in v1.3.0 

type CycleFullDTO struct {
	Number                     int      `json:"number"`
	Name                       string   `json:"name"`
	Status                     string   `json:"status"`
	StartsAt                   string   `json:"startsAt"`
	EndsAt                     string   `json:"endsAt"`
	Progress                   float64  `json:"progress"`
	Description                string   `json:"description"`
	Team                       *TeamDTO `json:"team"`
	ScopeHistory               []int    `json:"scopeHistory"`
	CompletedScopeHistory      []int    `json:"completedScopeHistory"`
	InProgressScopeHistory     []int    `json:"inProgressScopeHistory"`
	IssueCountHistory          []int    `json:"issueCountHistory"`
	CompletedIssueCountHistory []int    `json:"completedIssueCountHistory"`
	CreatedAt                  string   `json:"createdAt"`
	UpdatedAt                  string   `json:"updatedAt"`
}

CycleFullDTO contains complete cycle details

func CycleToFullDTO added in v1.3.0 

func CycleToFullDTO(cycle *core.Cycle) CycleFullDTO

CycleToFullDTO converts a cycle to full DTO

type CycleMinimalDTO added in v1.3.0 

type CycleMinimalDTO struct {
	Number   int    `json:"number"`
	Status   string `json:"status"`
	StartsAt string `json:"startsAt"`
	EndsAt   string `json:"endsAt"`
}

CycleMinimalDTO contains only essential cycle fields

func CycleToMinimalDTO added in v1.3.0 

func CycleToMinimalDTO(cycle *core.Cycle) CycleMinimalDTO

CycleToMinimalDTO converts a cycle to minimal DTO

type CycleRefDTO added in v1.3.0 

type CycleRefDTO struct {
	ID     string `json:"id"`
	Number int    `json:"number"`
	Name   string `json:"name"`
}

CycleRefDTO is a minimal cycle reference

type EstimateScale added in v1.3.0 

type EstimateScale struct {
	Values []float64 `json:"values"`
	Labels []string  `json:"labels"`
}

EstimateScale represents the estimation scale for a team

type Format 

type Format string

Format specifies the level of detail in formatted output 

const (
	// Minimal returns only essential fields (~50 tokens per issue)
	Minimal Format = "minimal"
	// Compact returns commonly needed fields (~150 tokens per issue)
	Compact Format = "compact"
	// Detailed returns all fields with truncated comments (~500 tokens per issue)
	Detailed Format = "detailed"
	// Full returns all fields with untruncated comments
	Full Format = "full"
)

func ParseFormat 

func ParseFormat(s string) (Format, error)

ParseFormat parses a string into a Format with validation

func VerbosityToFormat added in v1.3.0 

func VerbosityToFormat(verbosity Verbosity) Format

VerbosityToFormat converts Verbosity back to legacy Format. This helper maintains backward compatibility during migration.

type Formatter 

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

Formatter formats Linear resources as ASCII text or JSON

func New 

func New() *Formatter

New creates a new Formatter

func (*Formatter) Comment 

func (f *Formatter) Comment(comment *core.Comment) string

Comment formats a single comment

func (*Formatter) CommentList 

func (f *Formatter) CommentList(comments []core.Comment, page *Pagination) string

CommentList formats a list of comments with optional pagination

func (*Formatter) Cycle 

func (f *Formatter) Cycle(cycle *core.Cycle, fmt Format) string

Cycle formats a single cycle

func (*Formatter) CycleAnalysis 

func (f *Formatter) CycleAnalysis(analysis *cycles.CycleAnalysis, teamName, assigneeName string, showRecommendation bool) string

CycleAnalysis formats cycle analytics data

func (*Formatter) CycleList 

func (f *Formatter) CycleList(cycles []core.Cycle, fmt Format, page *Pagination) string

CycleList formats a list of cycles with optional pagination

func (*Formatter) Issue 

func (f *Formatter) Issue(issue *core.Issue, fmt Format) string

Issue formats a single issue

func (*Formatter) IssueList 

func (f *Formatter) IssueList(issues []core.Issue, fmt Format, page *Pagination) string

IssueList formats a list of issues with optional pagination

func (*Formatter) Project 

func (f *Formatter) Project(project *core.Project) string

Project formats a single project

func (*Formatter) ProjectList 

func (f *Formatter) ProjectList(projects []core.Project, page *Pagination) string

ProjectList formats a list of projects with optional pagination

func (*Formatter) RenderAttachment added in v1.5.0 

func (f *Formatter) RenderAttachment(att *core.Attachment, verbosity Verbosity, outputType OutputType) string

RenderAttachment renders a single attachment

func (*Formatter) RenderAttachmentList added in v1.5.0 

func (f *Formatter) RenderAttachmentList(atts []core.Attachment, verbosity Verbosity, outputType OutputType) string

RenderAttachmentList renders a list of attachments

func (*Formatter) RenderComment added in v1.3.0 

func (f *Formatter) RenderComment(comment *core.Comment, verbosity Verbosity, outputType OutputType) string

RenderComment renders a single comment with the specified verbosity and output type

func (*Formatter) RenderCommentList added in v1.3.0 

func (f *Formatter) RenderCommentList(comments []core.Comment, verbosity Verbosity, outputType OutputType) string

RenderCommentList renders a list of comments with the specified verbosity and output type

func (*Formatter) RenderCycle added in v1.3.0 

func (f *Formatter) RenderCycle(cycle *core.Cycle, verbosity Verbosity, outputType OutputType) string

RenderCycle renders a single cycle with the specified verbosity and output type

func (*Formatter) RenderCycleList added in v1.3.0 

func (f *Formatter) RenderCycleList(cycles []core.Cycle, verbosity Verbosity, outputType OutputType, page *Pagination) string

RenderCycleList renders a list of cycles with the specified verbosity and output type

func (*Formatter) RenderIssue added in v1.3.0 

func (f *Formatter) RenderIssue(issue *core.Issue, verbosity Verbosity, outputType OutputType) string

RenderIssue renders a single issue with the specified verbosity and output type

func (*Formatter) RenderIssueList added in v1.3.0 

func (f *Formatter) RenderIssueList(issues []core.Issue, verbosity Verbosity, outputType OutputType, page *Pagination) string

RenderIssueList renders a list of issues with the specified verbosity and output type

func (*Formatter) RenderProject added in v1.3.0 

func (f *Formatter) RenderProject(project *core.Project, verbosity Verbosity, outputType OutputType) string

RenderProject renders a single project with the specified verbosity and output type

func (*Formatter) RenderProjectList added in v1.3.0 

func (f *Formatter) RenderProjectList(projects []core.Project, verbosity Verbosity, outputType OutputType, page *Pagination) string

RenderProjectList renders a list of projects with the specified verbosity and output type

func (*Formatter) RenderTeam added in v1.3.0 

func (f *Formatter) RenderTeam(team *core.Team, verbosity Verbosity, outputType OutputType) string

RenderTeam renders a single team with the specified verbosity and output type

func (*Formatter) RenderTeamList added in v1.3.0 

func (f *Formatter) RenderTeamList(teams []core.Team, verbosity Verbosity, outputType OutputType) string

RenderTeamList renders a list of teams with the specified verbosity and output type

func (*Formatter) RenderUser added in v1.3.0 

func (f *Formatter) RenderUser(user *core.User, verbosity Verbosity, outputType OutputType) string

RenderUser renders a single user with the specified verbosity and output type

func (*Formatter) RenderUserList added in v1.3.0 

func (f *Formatter) RenderUserList(users []core.User, verbosity Verbosity, outputType OutputType) string

RenderUserList renders a list of users with the specified verbosity and output type

func (*Formatter) Team 

func (f *Formatter) Team(team *core.Team) string

Team formats a single team

func (*Formatter) TeamList 

func (f *Formatter) TeamList(teams []core.Team, page *Pagination) string

TeamList formats a list of teams with optional pagination

func (*Formatter) User 

func (f *Formatter) User(user *core.User) string

User formats a single user

func (*Formatter) UserList 

func (f *Formatter) UserList(users []core.User, page *Pagination) string

UserList formats a list of users with optional pagination

type IssueCompactDTO added in v1.3.0 

type IssueCompactDTO struct {
	Identifier  string   `json:"identifier"`
	Title       string   `json:"title"`
	State       string   `json:"state"`
	Priority    *int     `json:"priority"`
	Assignee    *string  `json:"assignee"`
	Delegate    *string  `json:"delegate,omitempty"` // OAuth app delegate
	Estimate    *float64 `json:"estimate"`
	DueDate     *string  `json:"dueDate"`
	CycleNumber *int     `json:"cycleNumber"`
	ProjectName *string  `json:"projectName"`
	CreatedAt   string   `json:"createdAt"`
	UpdatedAt   string   `json:"updatedAt"`
}

IssueCompactDTO contains key metadata (~150 tokens)

func IssueToCompactDTO added in v1.3.0 

func IssueToCompactDTO(issue *core.Issue) IssueCompactDTO

IssueToCompactDTO converts an issue to compact DTO

type IssueDetailedDTO added in v1.5.0 

type IssueDetailedDTO struct {
	Comments []CommentSummaryDTO `json:"comments"`
	// contains filtered or unexported fields
}

IssueDetailedDTO contains complete issue details with truncated comments (~500 tokens)

func IssueToDetailedDTO added in v1.5.0 

func IssueToDetailedDTO(issue *core.Issue) IssueDetailedDTO

IssueToDetailedDTO converts an issue to detailed DTO (truncated comments)

type IssueFullDTO added in v1.3.0 

type IssueFullDTO struct {
	Comments []CommentDTO `json:"comments"`
	// contains filtered or unexported fields
}

IssueFullDTO contains complete issue details (~500 tokens)

func IssueToFullDTO added in v1.3.0 

func IssueToFullDTO(issue *core.Issue) IssueFullDTO

IssueToFullDTO converts an issue to full DTO

type IssueMinimalDTO added in v1.3.0 

type IssueMinimalDTO struct {
	Identifier string `json:"identifier"`
	Title      string `json:"title"`
	State      string `json:"state"`
}

IssueMinimalDTO contains only essential issue fields (~50 tokens)

func IssueToMinimalDTO added in v1.3.0 

func IssueToMinimalDTO(issue *core.Issue) IssueMinimalDTO

IssueToMinimalDTO converts an issue to minimal DTO

type IssueRefDTO added in v1.3.0 

type IssueRefDTO struct {
	Identifier string `json:"identifier"`
	Title      string `json:"title"`
	State      string `json:"state"`
}

IssueRefDTO is a minimal issue reference

type JSONRenderer added in v1.3.0 

type JSONRenderer struct{}

JSONRenderer renders Linear resources as JSON. This provides machine-readable output for scripting and automation.

func (*JSONRenderer) RenderAttachment added in v1.5.0 

func (r *JSONRenderer) RenderAttachment(att *core.Attachment, verbosity Verbosity) string

func (*JSONRenderer) RenderAttachmentList added in v1.5.0 

func (r *JSONRenderer) RenderAttachmentList(atts []core.Attachment, verbosity Verbosity) string

func (*JSONRenderer) RenderComment added in v1.3.0 

func (r *JSONRenderer) RenderComment(comment *core.Comment, verbosity Verbosity) string

func (*JSONRenderer) RenderCommentList added in v1.3.0 

func (r *JSONRenderer) RenderCommentList(comments []core.Comment, verbosity Verbosity) string

func (*JSONRenderer) RenderCycle added in v1.3.0 

func (r *JSONRenderer) RenderCycle(cycle *core.Cycle, verbosity Verbosity) string

func (*JSONRenderer) RenderCycleList added in v1.3.0 

func (r *JSONRenderer) RenderCycleList(cycles []core.Cycle, verbosity Verbosity, page *Pagination) string

func (*JSONRenderer) RenderIssue added in v1.3.0 

func (r *JSONRenderer) RenderIssue(issue *core.Issue, verbosity Verbosity) string

func (*JSONRenderer) RenderIssueList added in v1.3.0 

func (r *JSONRenderer) RenderIssueList(issues []core.Issue, verbosity Verbosity, page *Pagination) string

func (*JSONRenderer) RenderProject added in v1.3.0 

func (r *JSONRenderer) RenderProject(project *core.Project, verbosity Verbosity) string

func (*JSONRenderer) RenderProjectList added in v1.3.0 

func (r *JSONRenderer) RenderProjectList(projects []core.Project, verbosity Verbosity, page *Pagination) string

func (*JSONRenderer) RenderTeam added in v1.3.0 

func (r *JSONRenderer) RenderTeam(team *core.Team, verbosity Verbosity) string

func (*JSONRenderer) RenderTeamList added in v1.3.0 

func (r *JSONRenderer) RenderTeamList(teams []core.Team, verbosity Verbosity) string

func (*JSONRenderer) RenderUser added in v1.3.0 

func (r *JSONRenderer) RenderUser(user *core.User, verbosity Verbosity) string

func (*JSONRenderer) RenderUserList added in v1.3.0 

func (r *JSONRenderer) RenderUserList(users []core.User, verbosity Verbosity) string

type LabelDTO added in v1.3.0 

type LabelDTO struct {
	ID   string `json:"id"`
	Name string `json:"name"`
}

LabelDTO represents an issue label

type OutputType added in v1.3.0 

type OutputType string

OutputType specifies the renderer to use for formatting output. 

const (
	// OutputText renders output as ASCII text (default, token-efficient)
	OutputText OutputType = "text"
	// OutputJSON renders output as JSON (machine-readable)
	OutputJSON OutputType = "json"
)

func ParseOutputType added in v1.3.0 

func ParseOutputType(s string) (OutputType, error)

ParseOutputType parses a string into an OutputType with validation. Returns OutputText for empty strings (default behavior).

func (OutputType) IsJSON added in v1.3.0 

func (o OutputType) IsJSON() bool

IsJSON returns true if this output type is JSON.

func (OutputType) IsText added in v1.3.0 

func (o OutputType) IsText() bool

IsText returns true if this output type is text.

func (OutputType) String added in v1.3.0 

func (o OutputType) String() string

String returns the string representation of the output type.

type Pagination 

type Pagination struct {
	Start       int  // Starting position (0-indexed)
	Limit       int  // Items per page
	Count       int  // Items in this page
	TotalCount  int  // Total items
	HasNextPage bool // More results exist
	// Deprecated: Use offset-based pagination instead
	EndCursor string // Cursor for cursor-based pagination
}

Pagination holds pagination metadata for list responses

type ProjectDTO added in v1.3.0 

type ProjectDTO struct {
	ID          string        `json:"id"`
	Name        string        `json:"name"`
	Description string        `json:"description"`
	State       string        `json:"state"`
	Content     string        `json:"content"`
	Issues      []IssueRefDTO `json:"issues"`
	CreatedAt   string        `json:"createdAt"`
	UpdatedAt   string        `json:"updatedAt"`
}

ProjectDTO represents a project in JSON format

func ProjectToDTO added in v1.3.0 

func ProjectToDTO(project *core.Project) ProjectDTO

ProjectToDTO converts a project to DTO

type ProjectRefDTO added in v1.3.0 

type ProjectRefDTO struct {
	ID   string `json:"id"`
	Name string `json:"name"`
}

ProjectRefDTO is a minimal project reference

type Renderer added in v1.3.0 

type Renderer interface {
	// Single entity rendering
	RenderIssue(issue *core.Issue, verbosity Verbosity) string
	RenderCycle(cycle *core.Cycle, verbosity Verbosity) string
	RenderProject(project *core.Project, verbosity Verbosity) string
	RenderTeam(team *core.Team, verbosity Verbosity) string
	RenderUser(user *core.User, verbosity Verbosity) string
	RenderComment(comment *core.Comment, verbosity Verbosity) string

	// List rendering with pagination
	RenderIssueList(issues []core.Issue, verbosity Verbosity, page *Pagination) string
	RenderCycleList(cycles []core.Cycle, verbosity Verbosity, page *Pagination) string
	RenderProjectList(projects []core.Project, verbosity Verbosity, page *Pagination) string
	RenderTeamList(teams []core.Team, verbosity Verbosity) string
	RenderUserList(users []core.User, verbosity Verbosity) string
	RenderCommentList(comments []core.Comment, verbosity Verbosity) string

	// Attachment rendering
	RenderAttachment(att *core.Attachment, verbosity Verbosity) string
	RenderAttachmentList(atts []core.Attachment, verbosity Verbosity) string
}

Renderer defines the interface for formatting Linear resources. Different implementations can render to text, JSON, or other formats.

type RendererFactory added in v1.3.0 

type RendererFactory struct{}

RendererFactory creates Renderer instances based on output type. This implements the Strategy Pattern for output format selection.

func NewRendererFactory added in v1.3.0 

func NewRendererFactory() *RendererFactory

NewRendererFactory creates a new RendererFactory.

func (*RendererFactory) GetRenderer added in v1.3.0 

func (f *RendererFactory) GetRenderer(outputType OutputType) Renderer

GetRenderer returns the appropriate renderer for the given output type. Defaults to TextRenderer if the output type is unknown.

type StateDTO added in v1.3.0 

type StateDTO struct {
	ID   string `json:"id"`
	Name string `json:"name"`
}

StateDTO represents workflow state

type TeamDTO added in v1.3.0 

type TeamDTO struct {
	ID                  string         `json:"id"`
	Key                 string         `json:"key"`
	Name                string         `json:"name"`
	Description         string         `json:"description"`
	IssueEstimationType string         `json:"issueEstimationType"`
	EstimateScale       *EstimateScale `json:"estimateScale"`
}

TeamDTO represents a team in JSON format

func TeamToDTO added in v1.3.0 

func TeamToDTO(team *core.Team) TeamDTO

TeamToDTO converts a team to DTO

type TeamRef added in v1.3.0 

type TeamRef struct {
	Key  string `json:"key"`
	Name string `json:"name"`
}

TeamRef is a minimal team reference

type TextRenderer added in v1.3.0 

type TextRenderer struct{}

TextRenderer renders Linear resources as ASCII text. This preserves the original token-efficient formatting behavior.

func (*TextRenderer) RenderAttachment added in v1.5.0 

func (r *TextRenderer) RenderAttachment(att *core.Attachment, verbosity Verbosity) string

func (*TextRenderer) RenderAttachmentList added in v1.5.0 

func (r *TextRenderer) RenderAttachmentList(atts []core.Attachment, verbosity Verbosity) string

func (*TextRenderer) RenderComment added in v1.3.0 

func (r *TextRenderer) RenderComment(comment *core.Comment, verbosity Verbosity) string

func (*TextRenderer) RenderCommentList added in v1.3.0 

func (r *TextRenderer) RenderCommentList(comments []core.Comment, verbosity Verbosity) string

func (*TextRenderer) RenderCycle added in v1.3.0 

func (r *TextRenderer) RenderCycle(cycle *core.Cycle, verbosity Verbosity) string

func (*TextRenderer) RenderCycleList added in v1.3.0 

func (r *TextRenderer) RenderCycleList(cycles []core.Cycle, verbosity Verbosity, page *Pagination) string

func (*TextRenderer) RenderIssue added in v1.3.0 

func (r *TextRenderer) RenderIssue(issue *core.Issue, verbosity Verbosity) string

func (*TextRenderer) RenderIssueList added in v1.3.0 

func (r *TextRenderer) RenderIssueList(issues []core.Issue, verbosity Verbosity, page *Pagination) string

func (*TextRenderer) RenderProject added in v1.3.0 

func (r *TextRenderer) RenderProject(project *core.Project, verbosity Verbosity) string

func (*TextRenderer) RenderProjectList added in v1.3.0 

func (r *TextRenderer) RenderProjectList(projects []core.Project, verbosity Verbosity, page *Pagination) string

func (*TextRenderer) RenderTeam added in v1.3.0 

func (r *TextRenderer) RenderTeam(team *core.Team, verbosity Verbosity) string

func (*TextRenderer) RenderTeamList added in v1.3.0 

func (r *TextRenderer) RenderTeamList(teams []core.Team, verbosity Verbosity) string

func (*TextRenderer) RenderUser added in v1.3.0 

func (r *TextRenderer) RenderUser(user *core.User, verbosity Verbosity) string

func (*TextRenderer) RenderUserList added in v1.3.0 

func (r *TextRenderer) RenderUserList(users []core.User, verbosity Verbosity) string

type UserDTO added in v1.3.0 

type UserDTO struct {
	ID          string    `json:"id"`
	Name        string    `json:"name"`
	DisplayName string    `json:"displayName"`
	Email       string    `json:"email"`
	Active      bool      `json:"active"`
	Admin       bool      `json:"admin"`
	Teams       []TeamRef `json:"teams"`
	CreatedAt   string    `json:"createdAt"`
}

UserDTO represents a user in JSON format

func UserToDTO added in v1.3.0 

func UserToDTO(user *core.User) UserDTO

UserToDTO converts a user to DTO

type Verbosity added in v1.3.0 

type Verbosity int

Verbosity specifies the level of detail in formatted output. This replaces the older Format type with clearer semantics. 

const (
	// VerbosityMinimal returns only essential fields (~50 tokens per issue)
	VerbosityMinimal Verbosity = iota
	// VerbosityCompact returns commonly needed fields (~150 tokens per issue)
	VerbosityCompact
	// VerbosityDetailed returns all fields with truncated comments (~500 tokens per issue)
	VerbosityDetailed
	// VerbosityFull returns all fields with untruncated comments
	VerbosityFull
)

func FormatToVerbosity added in v1.3.0 

func FormatToVerbosity(format Format) Verbosity

FormatToVerbosity converts the legacy Format type to Verbosity. This helper maintains backward compatibility during migration.

func ParseVerbosity added in v1.3.0 

func ParseVerbosity(s string) (Verbosity, error)

ParseVerbosity parses a string into a Verbosity with validation. Returns VerbosityCompact for empty strings (default behavior).

func (Verbosity) String added in v1.3.0 

func (v Verbosity) String() string

String returns the string representation of the verbosity level.

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.