feat: add public format package for issue rendering (#2871)

* feat: add public format package for issue rendering

Exposes issue formatting functions that were previously internal to the
bd CLI (cmd/bd/list_format.go). Consumers like gt can now render
issue output identically to bd without shelling out.

Public functions:
- PrettyIssue: one-line list format (status icon + ID + priority + title)
- CompactIssue: with assignee, labels, dependency annotations
- LongIssue: full detail with description
- DependencyInfo: "(parent: X, blocked by: Y, blocks: Z)" string
- StatusIcon: raw icon character without styling
- ListSummary: footer with total and status breakdown

Uses internal/ui for consistent styling (colors, muted, icons).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* test: add format package tests

Tests for StatusIcon, DependencyInfo, PrettyIssue (open, epic, closed),
LongIssue (with assignee, labels, description), and ListSummary.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: mayor <jim@wordelman.name>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Jim Wordelman 2026-04-02 19:33:53 -07:00 • committed by GitHub
commit 4d88e4ac75
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 325 additions and 0 deletions

188
format/format.go Normal file
View file

@ -0,0 +1,188 @@
// Package format provides public formatting functions for beads issues.
// These functions are used by gt and other consumers to render issue
// output without depending on the bd CLI.
package format
import (
"fmt"
"strings"
"github.com/steveyegge/beads/internal/types"
"github.com/steveyegge/beads/internal/ui"
)
// PrettyIssue formats a single issue in the standard one-line list format.
// Output: STATUS_ICON ID PRIORITY [Type] Title
func PrettyIssue(issue *types.Issue) string {
statusIcon := ui.RenderStatusIcon(string(issue.Status))
priorityTag := ui.RenderPriority(issue.Priority)
typeBadge := ""
switch issue.IssueType {
case "epic":
typeBadge = ui.TypeEpicStyle.Render("[epic]") + " "
case "bug":
typeBadge = ui.TypeBugStyle.Render("[bug]") + " "
}
if issue.Status == types.StatusClosed {
return fmt.Sprintf("%s %s %s %s%s",
statusIcon,
ui.RenderMuted(issue.ID),
ui.RenderMuted(fmt.Sprintf("● P%d", issue.Priority)),
ui.RenderMuted(string(issue.IssueType)),
ui.RenderMuted(" "+issue.Title))
}
return fmt.Sprintf("%s %s %s %s%s", statusIcon, issue.ID, priorityTag, typeBadge, issue.Title)
}
// CompactIssue formats an issue with optional assignee, labels, and dependency info.
// Output: STATUS_ICON ID [Priority] [Type] @assignee [labels] - Title (deps)
func CompactIssue(issue *types.Issue, labels []string, blockedBy, blocks []string, parent string) string {
var buf strings.Builder
labelsStr := ""
if len(labels) > 0 {
labelsStr = fmt.Sprintf(" %v", labels)
}
assigneeStr := ""
if issue.Assignee != "" {
assigneeStr = fmt.Sprintf(" @%s", issue.Assignee)
}
depInfo := DependencyInfo(blockedBy, blocks, parent)
if depInfo != "" {
depInfo = " " + depInfo
}
statusIcon := ui.RenderStatusIcon(string(issue.Status))
if issue.Status == types.StatusClosed {
pinPrefix := ""
if issue.Pinned {
pinPrefix = "📌 "
}
line := fmt.Sprintf("%s %s%s [P%d] [%s]%s%s - %s%s",
statusIcon, pinPrefix, issue.ID, issue.Priority,
issue.IssueType, assigneeStr, labelsStr, issue.Title, depInfo)
buf.WriteString(ui.RenderClosedLine(line))
} else {
pinPrefix := ""
if issue.Pinned {
pinPrefix = "📌 "
}
buf.WriteString(fmt.Sprintf("%s %s%s [%s] [%s]%s%s - %s%s",
statusIcon,
pinPrefix,
ui.RenderID(issue.ID),
ui.RenderPriority(issue.Priority),
ui.RenderType(string(issue.IssueType)),
assigneeStr, labelsStr, issue.Title, depInfo))
}
return buf.String()
}
// LongIssue formats a single issue in full detail.
func LongIssue(issue *types.Issue, labels []string) string {
var buf strings.Builder
status := string(issue.Status)
if status == "closed" {
pinPrefix := ""
if issue.Pinned {
pinPrefix = "📌 "
}
line := fmt.Sprintf("%s%s [P%d] [%s] %s\n %s",
pinPrefix, issue.ID, issue.Priority,
issue.IssueType, status, issue.Title)
buf.WriteString(ui.RenderClosedLine(line))
buf.WriteString("\n")
} else {
pinPrefix := ""
if issue.Pinned {
pinPrefix = "📌 "
}
buf.WriteString(fmt.Sprintf("%s%s [%s] [%s] %s\n",
pinPrefix,
ui.RenderID(issue.ID),
ui.RenderPriority(issue.Priority),
ui.RenderType(string(issue.IssueType)),
ui.RenderStatus(status)))
buf.WriteString(fmt.Sprintf(" %s\n", issue.Title))
}
if issue.Assignee != "" {
buf.WriteString(fmt.Sprintf(" Assignee: %s\n", issue.Assignee))
}
if len(labels) > 0 {
buf.WriteString(fmt.Sprintf(" Labels: %v\n", labels))
}
if issue.Description != "" {
buf.WriteString(fmt.Sprintf("\n%s\n", issue.Description))
}
return buf.String()
}
// DependencyInfo formats dependency info string.
// Returns "(parent: X, blocked by: Y, blocks: Z)" or "" if no dependencies.
func DependencyInfo(blockedBy, blocks []string, parent string) string {
if len(blockedBy) == 0 && len(blocks) == 0 && parent == "" {
return ""
}
var parts []string
if parent != "" {
parts = append(parts, fmt.Sprintf("parent: %s", parent))
}
if len(blockedBy) > 0 {
parts = append(parts, fmt.Sprintf("blocked by: %s", strings.Join(blockedBy, ", ")))
}
if len(blocks) > 0 {
parts = append(parts, fmt.Sprintf("blocks: %s", strings.Join(blocks, ", ")))
}
return "(" + strings.Join(parts, ", ") + ")"
}
// StatusIcon returns the status icon character without styling.
func StatusIcon(status string) string {
switch status {
case "open":
return "○"
case "in_progress":
return "◐"
case "blocked":
return "●"
case "closed":
return "✓"
case "deferred":
return "❄"
case "hooked":
return "◇"
case "pinned":
return "📌"
default:
return "○"
}
}
// ListSummary formats the summary footer for a list of issues.
func ListSummary(total int, byCounts map[string]int) string {
if total == 0 {
return "No issues found."
}
var parts []string
for status, count := range byCounts {
if count > 0 {
parts = append(parts, fmt.Sprintf("%d %s", count, status))
}
}
summary := fmt.Sprintf("Total: %d issues", total)
if len(parts) > 0 {
summary += " (" + strings.Join(parts, ", ") + ")"
}
return summary
}

137
format/format_test.go Normal file
View file

@ -0,0 +1,137 @@
package format
import (
"strings"
"testing"
"github.com/steveyegge/beads/internal/types"
)
func TestStatusIcon(t *testing.T) {
tests := []struct {
status string
want string
}{
{"open", "○"},
{"in_progress", "◐"},
{"blocked", "●"},
{"closed", "✓"},
{"deferred", "❄"},
{"hooked", "◇"},
{"pinned", "📌"},
{"unknown", "○"},
{"", "○"},
}
for _, tt := range tests {
t.Run(tt.status, func(t *testing.T) {
if got := StatusIcon(tt.status); got != tt.want {
t.Errorf("StatusIcon(%q) = %q, want %q", tt.status, got, tt.want)
}
})
}
}
func TestDependencyInfo(t *testing.T) {
tests := []struct {
name string
blockedBy []string
blocks []string
parent string
want string
}{
{"empty", nil, nil, "", ""},
{"parent only", nil, nil, "epic-1", "(parent: epic-1)"},
{"blocked by", []string{"a", "b"}, nil, "", "(blocked by: a, b)"},
{"blocks", nil, []string{"c"}, "", "(blocks: c)"},
{"all", []string{"a"}, []string{"b"}, "p", "(parent: p, blocked by: a, blocks: b)"},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
if got := DependencyInfo(tt.blockedBy, tt.blocks, tt.parent); got != tt.want {
t.Errorf("DependencyInfo() = %q, want %q", got, tt.want)
}
})
}
}
func TestPrettyIssue(t *testing.T) {
issue := &types.Issue{
ID: "gas-abc",
Title: "Fix the thing",
Status: types.StatusOpen,
Priority: 2,
IssueType: "task",
}
got := PrettyIssue(issue)
if !strings.Contains(got, "gas-abc") {
t.Errorf("PrettyIssue missing ID: %q", got)
}
if !strings.Contains(got, "Fix the thing") {
t.Errorf("PrettyIssue missing title: %q", got)
}
}
func TestPrettyIssue_Epic(t *testing.T) {
issue := &types.Issue{
ID: "gas-xyz",
Title: "Big project",
Status: types.StatusOpen,
Priority: 1,
IssueType: "epic",
}
got := PrettyIssue(issue)
if !strings.Contains(got, "[epic]") {
t.Errorf("PrettyIssue missing epic badge: %q", got)
}
}
func TestPrettyIssue_Closed(t *testing.T) {
issue := &types.Issue{
ID: "gas-done",
Title: "Completed work",
Status: types.StatusClosed,
Priority: 2,
IssueType: "task",
}
got := PrettyIssue(issue)
if !strings.Contains(got, "gas-done") {
t.Errorf("PrettyIssue closed missing ID: %q", got)
}
}
func TestListSummary(t *testing.T) {
got := ListSummary(0, nil)
if got != "No issues found." {
t.Errorf("ListSummary(0) = %q", got)
}
got = ListSummary(5, map[string]int{"open": 3, "closed": 2})
if !strings.Contains(got, "Total: 5 issues") {
t.Errorf("ListSummary(5) = %q", got)
}
}
func TestLongIssue(t *testing.T) {
issue := &types.Issue{
ID: "gas-abc",
Title: "Fix the thing",
Status: types.StatusOpen,
Priority: 2,
IssueType: "task",
Assignee: "mayor",
Description: "A longer description",
}
got := LongIssue(issue, []string{"gt:task"})
if !strings.Contains(got, "gas-abc") {
t.Errorf("LongIssue missing ID: %q", got)
}
if !strings.Contains(got, "mayor") {
t.Errorf("LongIssue missing assignee: %q", got)
}
if !strings.Contains(got, "A longer description") {
t.Errorf("LongIssue missing description: %q", got)
}
if !strings.Contains(got, "gt:task") {
t.Errorf("LongIssue missing labels: %q", got)
}
}