report

package
v0.33.0 Latest Latest
Warning

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

 Go to latest Published: Aug 24, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package report provides a report generation system for Jira data. It defines a report schema that can be transformed into Dashforge Dashboard IR for rendering as interactive dashboards or static exports.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ParseSectionConfig 

func ParseSectionConfig[T any](section *Section) (*T, error)

ParseSectionConfig parses a section's config into the appropriate type.

Types

type BurndownConfig 

type BurndownConfig struct {
	SprintID         int    `json:"sprint_id" yaml:"sprint_id"`
	SprintName       string `json:"sprint_name,omitempty" yaml:"sprint_name,omitempty"`
	StoryPointsField string `json:"story_points_field,omitempty" yaml:"story_points_field,omitempty"`
	ShowIdealLine    bool   `json:"show_ideal_line,omitempty" yaml:"show_ideal_line,omitempty"`
}

BurndownConfig configures a burndown chart section.

type BurndownProcessor 

type BurndownProcessor struct {
	Client *jira.Client
	// contains filtered or unexported fields
}

BurndownProcessor processes burndown chart sections.

func (*BurndownProcessor) Process 

func (p *BurndownProcessor) Process(ctx *ExecutionContext, section *Section) (*SectionResult, error)

Process generates burndown chart data for a sprint.

type Cache 

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

Cache provides caching for Jira API responses.

func NewCache 

func NewCache(ttl time.Duration) *Cache

NewCache creates a new cache with the given TTL.

func (*Cache) Clear 

func (c *Cache) Clear()

Clear clears the cache.

func (*Cache) Get 

func (c *Cache) Get(key string) (any, bool)

Get retrieves a value from the cache.

func (*Cache) Set 

func (c *Cache) Set(key string, value any)

Set stores a value in the cache.

type ChartConfigIR 

type ChartConfigIR struct {
	Type    string          `json:"type"` // "bar", "line", "pie", "area"
	XField  string          `json:"xField,omitempty"`
	YFields []string        `json:"yFields,omitempty"`
	Series  []SeriesIR      `json:"series,omitempty"`
	Options json.RawMessage `json:"options,omitempty"`
}

ChartConfigIR defines chart configuration.

type ColumnIR 

type ColumnIR struct {
	Field    string `json:"field"`
	Header   string `json:"header"`
	Width    string `json:"width,omitempty"`
	Sortable bool   `json:"sortable,omitempty"`
	Format   string `json:"format,omitempty"`
}

ColumnIR defines a table column.

type CycleTimeConfig 

type CycleTimeConfig struct {
	JQL       string      `json:"jql,omitempty" yaml:"jql,omitempty"`
	SprintID  int         `json:"sprint_id,omitempty" yaml:"sprint_id,omitempty"`
	Display   DisplayType `json:"display" yaml:"display"`
	ChartType string      `json:"chart_type,omitempty" yaml:"chart_type,omitempty"`
}

CycleTimeConfig configures a cycle time analysis section.

type CycleTimeProcessor 

type CycleTimeProcessor struct {
	Client *jira.Client
	// contains filtered or unexported fields
}

CycleTimeProcessor processes cycle time analysis sections.

func (*CycleTimeProcessor) Process 

func (p *CycleTimeProcessor) Process(ctx *ExecutionContext, section *Section) (*SectionResult, error)

Process generates cycle time analysis data.

type DashboardIR 

type DashboardIR struct {
	ID          string         `json:"id"`
	Title       string         `json:"title"`
	Description string         `json:"description,omitempty"`
	Version     string         `json:"version,omitempty"`
	Layout      LayoutIR       `json:"layout"`
	DataSources []DataSourceIR `json:"dataSources"`
	Widgets     []WidgetIR     `json:"widgets"`
	Variables   []VariableIR   `json:"variables,omitempty"`
	Theme       *ThemeIR       `json:"theme,omitempty"`
}

DashboardIR represents a Dashforge Dashboard. This matches the Dashforge schema for compatibility.

func (*DashboardIR) ToJSON 

func (d *DashboardIR) ToJSON() ([]byte, error)

ToJSON converts the dashboard IR to JSON.

type DataSourceIR 

type DataSourceIR struct {
	ID        string          `json:"id"`
	Type      string          `json:"type"` // "inline", "url", "derived"
	Data      json.RawMessage `json:"data,omitempty"`
	URL       string          `json:"url,omitempty"`
	Transform []TransformIR   `json:"transform,omitempty"`
}

DataSourceIR defines a data source in the dashboard.

func NewInlineDataSource 

func NewInlineDataSource(id string, data any) (*DataSourceIR, error)

NewInlineDataSource creates an inline data source with the given data.

type Definition 

type Definition struct {
	ID          string `json:"id" yaml:"id"`
	Title       string `json:"title" yaml:"title"`
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
	Version     string `json:"version,omitempty" yaml:"version,omitempty"`

	Variables []Variable `json:"variables,omitempty" yaml:"variables,omitempty"`
	Sections  []Section  `json:"sections" yaml:"sections"`
	Theme     *Theme     `json:"theme,omitempty" yaml:"theme,omitempty"`

	// Metadata
	Author    string    `json:"author,omitempty" yaml:"author,omitempty"`
	CreatedAt time.Time `json:"created_at,omitempty" yaml:"created_at,omitempty"`
	UpdatedAt time.Time `json:"updated_at,omitempty" yaml:"updated_at,omitempty"`
}

Definition represents a complete Jira report definition.

func ParseFile 

func ParseFile(path string) (*Definition, error)

ParseFile parses a report definition from a file. The format is determined by the file extension (.yaml, .yml, or .json).

func ParseJSON 

func ParseJSON(r io.Reader) (*Definition, error)

ParseJSON parses a report definition from JSON.

func ParseJSONString 

func ParseJSONString(s string) (*Definition, error)

ParseJSONString parses a report definition from a JSON string.

func ParseYAML 

func ParseYAML(r io.Reader) (*Definition, error)

ParseYAML parses a report definition from YAML.

func ParseYAMLString 

func ParseYAMLString(s string) (*Definition, error)

ParseYAMLString parses a report definition from a YAML string.

func (*Definition) ToJSON 

func (d *Definition) ToJSON() ([]byte, error)

ToJSON converts the definition to JSON.

func (*Definition) ToYAML 

func (d *Definition) ToYAML() ([]byte, error)

ToYAML converts the definition to YAML.

func (*Definition) Validate 

func (d *Definition) Validate() error

Validate validates the report definition.

type DisplayType 

type DisplayType string

DisplayType defines how data should be displayed. 

const (
	DisplayTable DisplayType = "table"
	DisplayChart DisplayType = "chart"
	DisplayList  DisplayType = "list"
)

Display types.

type Engine 

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

Engine executes report definitions and produces Dashforge IR.

func NewEngine 

func NewEngine(client *jira.Client) *Engine

NewEngine creates a new report engine.

func (*Engine) Execute 

func (e *Engine) Execute(ctx context.Context, def *Definition, vars map[string]any) (*DashboardIR, error)

Execute runs the report and returns a Dashforge Dashboard IR.

func (*Engine) RegisterProcessor 

func (e *Engine) RegisterProcessor(sectionType SectionType, processor SectionProcessor)

RegisterProcessor registers a custom section processor.

type ExecutionContext 

type ExecutionContext struct {
	Context   context.Context
	Variables map[string]any
	Cache     *Cache
}

ExecutionContext provides context for section processing.

func (*ExecutionContext) GetIntVariable 

func (c *ExecutionContext) GetIntVariable(name string) int

GetIntVariable returns an int variable value.

func (*ExecutionContext) GetStringVariable 

func (c *ExecutionContext) GetStringVariable(name string) string

GetStringVariable returns a string variable value.

func (*ExecutionContext) GetVariable 

func (c *ExecutionContext) GetVariable(name string) (any, bool)

GetVariable returns a variable value.

type JQLConfig 

type JQLConfig struct {
	JQL        string      `json:"jql" yaml:"jql"`
	Fields     []string    `json:"fields,omitempty" yaml:"fields,omitempty"`
	MaxResults int         `json:"max_results,omitempty" yaml:"max_results,omitempty"`
	Display    DisplayType `json:"display" yaml:"display"`
	ChartType  string      `json:"chart_type,omitempty" yaml:"chart_type,omitempty"`
	GroupBy    string      `json:"group_by,omitempty" yaml:"group_by,omitempty"`
}

JQLConfig configures a JQL-based section.

type JQLProcessor 

type JQLProcessor struct {
	Client *jira.Client
	// contains filtered or unexported fields
}

JQLProcessor processes JQL query sections.

func (*JQLProcessor) Process 

func (p *JQLProcessor) Process(ctx *ExecutionContext, section *Section) (*SectionResult, error)

Process executes a JQL query and produces appropriate widget.

type LayoutIR 

type LayoutIR struct {
	Columns    int  `json:"columns"`
	RowHeight  int  `json:"rowHeight,omitempty"`
	Responsive bool `json:"responsive,omitempty"`
}

LayoutIR defines the dashboard grid layout.

type MarkdownProcessor 

type MarkdownProcessor struct{}

MarkdownProcessor processes markdown sections.

func (*MarkdownProcessor) Process 

func (p *MarkdownProcessor) Process(ctx *ExecutionContext, section *Section) (*SectionResult, error)

Process converts a markdown section to a text widget.

type MetricComparison 

type MetricComparison struct {
	Type        string  `json:"type" yaml:"type"`
	TargetValue float64 `json:"target_value,omitempty" yaml:"target_value,omitempty"`
}

MetricComparison defines comparison for a metric.

type MetricConfig 

type MetricConfig struct {
	JQL         string            `json:"jql,omitempty" yaml:"jql,omitempty"`
	Aggregation string            `json:"aggregation" yaml:"aggregation"`
	Field       string            `json:"field,omitempty" yaml:"field,omitempty"`
	Format      string            `json:"format,omitempty" yaml:"format,omitempty"`
	Comparison  *MetricComparison `json:"comparison,omitempty" yaml:"comparison,omitempty"`
}

MetricConfig configures a single metric display.

type MetricConfigIR 

type MetricConfigIR struct {
	ValueField      string  `json:"valueField"`
	Format          string  `json:"format,omitempty"` // "number", "percent", "duration"
	Prefix          string  `json:"prefix,omitempty"`
	Suffix          string  `json:"suffix,omitempty"`
	ComparisonValue float64 `json:"comparisonValue,omitempty"`
	ComparisonType  string  `json:"comparisonType,omitempty"` // "increase", "decrease"
}

MetricConfigIR defines metric widget configuration.

type MetricProcessor 

type MetricProcessor struct {
	Client *jira.Client
	// contains filtered or unexported fields
}

MetricProcessor processes single metric display sections.

func (*MetricProcessor) Process 

func (p *MetricProcessor) Process(ctx *ExecutionContext, section *Section) (*SectionResult, error)

Process generates a metric widget.

type Position 

type Position struct {
	X int `json:"x" yaml:"x"`
	Y int `json:"y" yaml:"y"`
	W int `json:"w" yaml:"w"`
	H int `json:"h" yaml:"h"`
}

Position defines the grid position of a section.

type PositionIR 

type PositionIR struct {
	X int `json:"x"`
	Y int `json:"y"`
	W int `json:"w"`
	H int `json:"h"`
}

PositionIR defines the grid position of a widget.

type Section 

type Section struct {
	ID       string          `json:"id" yaml:"id"`
	Type     SectionType     `json:"type" yaml:"type"`
	Title    string          `json:"title,omitempty" yaml:"title,omitempty"`
	Position *Position       `json:"position,omitempty" yaml:"position,omitempty"`
	Config   json.RawMessage `json:"config,omitempty" yaml:"-"`

	// Convenience fields (parsed from Config or set directly)
	Content string `json:"content,omitempty" yaml:"content,omitempty"` // For markdown
}

Section represents a single section in the report.

func (*Section) GetBurndownConfig 

func (s *Section) GetBurndownConfig() (*BurndownConfig, error)

GetBurndownConfig extracts burndown config from a section.

func (*Section) GetCycleTimeConfig 

func (s *Section) GetCycleTimeConfig() (*CycleTimeConfig, error)

GetCycleTimeConfig extracts cycle time config from a section.

func (*Section) GetJQLConfig 

func (s *Section) GetJQLConfig() (*JQLConfig, error)

GetJQLConfig extracts JQL config from a section.

func (*Section) GetMetricConfig 

func (s *Section) GetMetricConfig() (*MetricConfig, error)

GetMetricConfig extracts metric config from a section.

func (*Section) GetTableConfig 

func (s *Section) GetTableConfig() (*TableConfig, error)

GetTableConfig extracts table config from a section.

func (*Section) GetVelocityConfig 

func (s *Section) GetVelocityConfig() (*VelocityConfig, error)

GetVelocityConfig extracts velocity config from a section.

func (*Section) GetWorklogConfig 

func (s *Section) GetWorklogConfig() (*WorklogConfig, error)

GetWorklogConfig extracts worklog config from a section.

func (*Section) UnmarshalYAML 

func (s *Section) UnmarshalYAML(unmarshal func(interface{}) error) error

UnmarshalYAML implements custom YAML unmarshaling for Section.

func (*Section) Validate 

func (s *Section) Validate() error

Validate validates a section.

type SectionProcessor 

type SectionProcessor interface {
	Process(ctx *ExecutionContext, section *Section) (*SectionResult, error)
}

SectionProcessor processes a section and produces widget IR.

type SectionResult 

type SectionResult struct {
	Widget     WidgetIR
	DataSource *DataSourceIR
}

SectionResult contains the output of processing a section.

type SectionType 

type SectionType string

SectionType defines the type of a report section. 

const (
	SectionTypeMarkdown  SectionType = "markdown"
	SectionTypeJQL       SectionType = "jql"
	SectionTypeVelocity  SectionType = "velocity"
	SectionTypeBurndown  SectionType = "burndown"
	SectionTypeWorklog   SectionType = "worklog"
	SectionTypeCycleTime SectionType = "cycletime"
	SectionTypeMetric    SectionType = "metric"
	SectionTypeTable     SectionType = "table"
)

Section types.

type SelectOption 

type SelectOption struct {
	Value string `json:"value" yaml:"value"`
	Label string `json:"label" yaml:"label"`
}

SelectOption represents an option in a select variable.

type SeriesIR 

type SeriesIR struct {
	Name      string `json:"name"`
	DataField string `json:"dataField"`
	Color     string `json:"color,omitempty"`
}

SeriesIR defines a data series in a chart.

type TableConfig 

type TableConfig struct {
	JQL        string   `json:"jql,omitempty" yaml:"jql,omitempty"`
	Fields     []string `json:"fields" yaml:"fields"`
	MaxResults int      `json:"max_results,omitempty" yaml:"max_results,omitempty"`
	Sortable   bool     `json:"sortable,omitempty" yaml:"sortable,omitempty"`
	Paginated  bool     `json:"paginated,omitempty" yaml:"paginated,omitempty"`
}

TableConfig configures a table section.

type TableConfigIR 

type TableConfigIR struct {
	Columns   []ColumnIR `json:"columns"`
	Sortable  bool       `json:"sortable,omitempty"`
	Paginated bool       `json:"paginated,omitempty"`
	PageSize  int        `json:"pageSize,omitempty"`
}

TableConfigIR defines table configuration.

type TableProcessor 

type TableProcessor struct {
	Client *jira.Client
	// contains filtered or unexported fields
}

TableProcessor processes table sections.

func (*TableProcessor) Process 

func (p *TableProcessor) Process(ctx *ExecutionContext, section *Section) (*SectionResult, error)

Process generates a table widget.

type TextConfigIR 

type TextConfigIR struct {
	Content string `json:"content"`
	Format  string `json:"format,omitempty"` // "markdown", "html", "plain"
}

TextConfigIR defines text widget configuration.

type Theme 

type Theme struct {
	Colors   *ThemeColors `json:"colors,omitempty" yaml:"colors,omitempty"`
	FontSize string       `json:"font_size,omitempty" yaml:"font_size,omitempty"`
	DarkMode bool         `json:"dark_mode,omitempty" yaml:"dark_mode,omitempty"`
}

Theme defines visual styling for the report.

type ThemeColors 

type ThemeColors struct {
	Primary   string `json:"primary,omitempty" yaml:"primary,omitempty"`
	Secondary string `json:"secondary,omitempty" yaml:"secondary,omitempty"`
	Success   string `json:"success,omitempty" yaml:"success,omitempty"`
	Warning   string `json:"warning,omitempty" yaml:"warning,omitempty"`
	Danger    string `json:"danger,omitempty" yaml:"danger,omitempty"`
}

ThemeColors defines color palette for the theme.

type ThemeColorsIR 

type ThemeColorsIR struct {
	Primary   string `json:"primary,omitempty"`
	Secondary string `json:"secondary,omitempty"`
	Success   string `json:"success,omitempty"`
	Warning   string `json:"warning,omitempty"`
	Danger    string `json:"danger,omitempty"`
}

ThemeColorsIR defines the theme color palette.

type ThemeIR 

type ThemeIR struct {
	Mode   string         `json:"mode,omitempty"` // "light", "dark"
	Colors *ThemeColorsIR `json:"colors,omitempty"`
}

ThemeIR defines the dashboard theme.

type TransformIR 

type TransformIR struct {
	Type   string          `json:"type"` // "filter", "aggregate", "sort", etc.
	Config json.RawMessage `json:"config"`
}

TransformIR defines a data transformation.

type ValidationError 

type ValidationError struct {
	Field   string
	Message string
	Index   int
	Cause   error
}

ValidationError represents a validation error.

func (*ValidationError) Error 

func (e *ValidationError) Error() string

func (*ValidationError) Unwrap 

func (e *ValidationError) Unwrap() error

type Variable 

type Variable struct {
	ID          string         `json:"id" yaml:"id"`
	Type        VariableType   `json:"type" yaml:"type"`
	Label       string         `json:"label" yaml:"label"`
	Description string         `json:"description,omitempty" yaml:"description,omitempty"`
	Default     any            `json:"default,omitempty" yaml:"default,omitempty"`
	Required    bool           `json:"required,omitempty" yaml:"required,omitempty"`
	Options     []SelectOption `json:"options,omitempty" yaml:"options,omitempty"`
}

Variable represents a configurable parameter in a report.

type VariableIR 

type VariableIR struct {
	ID      string         `json:"id"`
	Type    string         `json:"type"`
	Label   string         `json:"label"`
	Default any            `json:"default,omitempty"`
	Options []SelectOption `json:"options,omitempty"`
}

VariableIR defines a variable in the dashboard.

type VariableType 

type VariableType string

VariableType defines the type of a variable. 

const (
	VariableTypeString VariableType = "string"
	VariableTypeNumber VariableType = "number"
	VariableTypeDate   VariableType = "date"
	VariableTypeSelect VariableType = "select"
	VariableTypeBool   VariableType = "bool"
)

Variable types.

type VelocityConfig 

type VelocityConfig struct {
	BoardID          int    `json:"board_id" yaml:"board_id"`
	SprintCount      int    `json:"sprint_count,omitempty" yaml:"sprint_count,omitempty"`
	IncludeActive    bool   `json:"include_active,omitempty" yaml:"include_active,omitempty"`
	StoryPointsField string `json:"story_points_field,omitempty" yaml:"story_points_field,omitempty"`
	ChartType        string `json:"chart_type,omitempty" yaml:"chart_type,omitempty"`
}

VelocityConfig configures a velocity chart section.

type VelocityProcessor 

type VelocityProcessor struct {
	Client *jira.Client
	// contains filtered or unexported fields
}

VelocityProcessor processes velocity chart sections.

func (*VelocityProcessor) Process 

func (p *VelocityProcessor) Process(ctx *ExecutionContext, section *Section) (*SectionResult, error)

Process generates velocity chart data from sprint history.

type WidgetIR 

type WidgetIR struct {
	ID           string          `json:"id"`
	Type         string          `json:"type"` // "chart", "table", "metric", "text"
	Title        string          `json:"title,omitempty"`
	Position     *PositionIR     `json:"position"`
	DataSourceID string          `json:"dataSourceId,omitempty"`
	Config       json.RawMessage `json:"config"`
}

WidgetIR defines a widget in the dashboard.

func NewChartWidget 

func NewChartWidget(id, title string, pos *PositionIR, dataSourceID string, config *ChartConfigIR) (*WidgetIR, error)

NewChartWidget creates a chart widget.

func NewMetricWidget 

func NewMetricWidget(id, title string, pos *PositionIR, dataSourceID string, config *MetricConfigIR) (*WidgetIR, error)

NewMetricWidget creates a metric widget.

func NewTableWidget 

func NewTableWidget(id, title string, pos *PositionIR, dataSourceID string, config *TableConfigIR) (*WidgetIR, error)

NewTableWidget creates a table widget.

func NewTextWidget 

func NewTextWidget(id, title string, pos *PositionIR, config *TextConfigIR) (*WidgetIR, error)

NewTextWidget creates a text widget.

type WorklogConfig 

type WorklogConfig struct {
	JQL       string      `json:"jql,omitempty" yaml:"jql,omitempty"`
	SprintID  int         `json:"sprint_id,omitempty" yaml:"sprint_id,omitempty"`
	GroupBy   string      `json:"group_by,omitempty" yaml:"group_by,omitempty"`
	Display   DisplayType `json:"display" yaml:"display"`
	ChartType string      `json:"chart_type,omitempty" yaml:"chart_type,omitempty"`
}

WorklogConfig configures a worklog summary section.

type WorklogProcessor 

type WorklogProcessor struct {
	Client *jira.Client
	// contains filtered or unexported fields
}

WorklogProcessor processes worklog summary sections.

func (*WorklogProcessor) Process 

func (p *WorklogProcessor) Process(ctx *ExecutionContext, section *Section) (*SectionResult, error)

Process generates worklog summary data.

Source Files

View all Source files

Directories

Path Synopsis
Package export provides report export functionality.
 Package export provides report export functionality.
Package sections provides section processors for report generation.
 Package sections provides section processors for report generation.

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.