Help us shape the future of Go! Take the 2026 Go Developer Survey

format

package
v1.0.0 Latest Latest
Warning

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

Go to latest
Published: Mar 11, 2026 License: AGPL-3.0 Imports: 7 Imported by: 0

Documentation

Index

Constants

View Source
const CompactSchemaName = "trace/compact/v1"

CompactSchemaName is the schema identifier.

View Source
const CompactSchemaVersion = "1"

CompactSchemaVersion is the current compact schema version.

View Source
const FormatVersion = "1"

FormatVersion is the current version of the format specification.

Variables

View Source
var ASCIIChars = TreeChars{
	Branch:   "|-- ",
	LastItem: "`-- ",
	Vertical: "|   ",
	Arrow:    "->",
	Warning:  "[!]",
}

ASCIIChars are the ASCII fallback characters.

View Source
var CompactKeyMapping = map[string]string{
	"_v":    "version",
	"_s":    "schema",
	"_keys": "key_mapping",
	"q":     "query",
	"f":     "focus_nodes",
	"g":     "graph_stats",
	"k":     "key_nodes",
	"r":     "risk",
	"n":     "node_count",
	"e":     "edge_count",
	"d":     "depth",
	"i":     "id",
	"nm":    "name",
	"l":     "location",
	"t":     "type",
	"p":     "package",
	"c":     "callers",
	"o":     "callees",
	"fl":    "flag",
	"w":     "warning",
	"cn":    "connections",
	"ti":    "target_id",
	"ct":    "connection_type",
	"lv":    "level",
	"di":    "direct_impact",
	"ii":    "indirect_impact",
	"ws":    "warnings",
}

CompactKeyMapping maps short keys to full names.

View Source
var DefaultRegistry = NewFormatRegistry()

DefaultRegistry is the default format registry.

View Source
var ErrFormatNotSupported = errors.New("format not supported")

ErrFormatNotSupported is returned when a format type is not supported.

View Source
var ErrResultTooLarge = errors.New("result exceeds format capabilities")

ErrResultTooLarge is returned when a result exceeds format capabilities.

View Source
var TokenRatio = map[string]float64{
	"gpt4":    4.0,
	"claude":  3.5,
	"llama":   4.5,
	"default": 4.0,
}

TokenRatio maps tokenizer names to characters per token.

View Source
var UnicodeChars = TreeChars{
	Branch:   "├── ",
	LastItem: "└── ",
	Vertical: "│   ",
	Arrow:    "→",
	Warning:  "⚠️",
}

UnicodeChars are the Unicode tree characters.

Functions

func Format

func Format(result interface{}, formatType FormatType) (string, error)

Format formats a result using the default registry.

func GetSchema

func GetSchema() map[string]string

GetSchema returns the compact schema information.

Types

type CompactFormatter

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

CompactFormatter formats results as minimal-token JSON.

func NewCompactFormatter

func NewCompactFormatter() *CompactFormatter

NewCompactFormatter creates a new compact formatter.

func NewCompactFormatterNoSchema

func NewCompactFormatterNoSchema() *CompactFormatter

NewCompactFormatterNoSchema creates a compact formatter without schema info.

func (*CompactFormatter) Format

func (f *CompactFormatter) Format(result interface{}) (string, error)

Format converts the result to compact JSON string.

func (*CompactFormatter) FormatStreaming

func (f *CompactFormatter) FormatStreaming(result interface{}, w io.Writer) error

FormatStreaming is not supported for compact format.

func (*CompactFormatter) IsReversible

func (f *CompactFormatter) IsReversible() bool

IsReversible returns true - with schema, compact JSON is reversible.

func (*CompactFormatter) Name

func (f *CompactFormatter) Name() FormatType

Name returns the format name.

func (*CompactFormatter) SupportsStreaming

func (f *CompactFormatter) SupportsStreaming() bool

SupportsStreaming returns false - compact needs full data for compression.

func (*CompactFormatter) TokenEstimate

func (f *CompactFormatter) TokenEstimate(result interface{}, tokenizer ...string) int

TokenEstimate estimates the number of tokens.

type Connection

type Connection struct {
	// TargetID is the target node ID.
	TargetID string `json:"target_id"`

	// Type is the connection type (calls, called_by, implements, etc.).
	Type string `json:"type"`
}

Connection represents a connection between nodes.

type FormatCapability

type FormatCapability struct {
	// MaxNodes is the maximum number of nodes for visual formats.
	MaxNodes int

	// MaxRows is the maximum number of rows for table formats.
	MaxRows int

	// MaxTokens is the maximum estimated tokens.
	MaxTokens int

	// SupportsStreaming indicates if the format supports streaming.
	SupportsStreaming bool
}

FormatCapability defines the limits of a format.

type FormatMetadata

type FormatMetadata struct {
	// Type is the format type.
	Type FormatType `json:"type"`

	// Version is the format specification version.
	Version string `json:"version"`

	// Reversible indicates if the output can be parsed back.
	Reversible bool `json:"reversible"`

	// Note is additional information about the format.
	Note string `json:"note,omitempty"`
}

FormatMetadata contains metadata about the formatted output.

type FormatRegistry

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

FormatRegistry manages format specifications and capabilities.

func NewFormatRegistry

func NewFormatRegistry() *FormatRegistry

NewFormatRegistry creates a new format registry with default formatters.

func (*FormatRegistry) AutoSelectFormat

func (r *FormatRegistry) AutoSelectFormat(result interface{}, tokenBudget int) FormatType

AutoSelectFormat selects the best format based on result size and token budget.

func (*FormatRegistry) Format

func (r *FormatRegistry) Format(result interface{}, formatType FormatType) (string, error)

Format formats a result with the specified format type.

func (*FormatRegistry) GetCapability

func (r *FormatRegistry) GetCapability(formatType FormatType) (FormatCapability, bool)

GetCapability returns the capability for a format type.

func (*FormatRegistry) GetFormatter

func (r *FormatRegistry) GetFormatter(formatType FormatType) (Formatter, error)

GetFormatter returns the formatter for the given type.

func (*FormatRegistry) GetMetadata

func (r *FormatRegistry) GetMetadata(formatType FormatType) (FormatMetadata, error)

GetMetadata returns metadata for a format type.

func (*FormatRegistry) ListFormats

func (r *FormatRegistry) ListFormats() []FormatType

ListFormats returns all supported format types.

func (*FormatRegistry) Register

func (r *FormatRegistry) Register(formatType FormatType, formatter Formatter)

Register registers a formatter for a format type.

func (*FormatRegistry) ValidateCapability

func (r *FormatRegistry) ValidateCapability(result interface{}, formatType FormatType) error

ValidateCapability checks if a result can be formatted with the given format.

type FormatType

type FormatType string

FormatType represents the type of output format.

const (
	// FormatJSON is full JSON output (default).
	FormatJSON FormatType = "json"

	// FormatOutline is tree-style text output.
	FormatOutline FormatType = "outline"

	// FormatCompact is minimal token JSON output.
	FormatCompact FormatType = "compact"

	// FormatMermaid is graph diagram output.
	FormatMermaid FormatType = "mermaid"

	// FormatMarkdown is table/list output.
	FormatMarkdown FormatType = "markdown"
)

func AutoSelectFormat

func AutoSelectFormat(result interface{}, tokenBudget int) FormatType

AutoSelectFormat selects a format using the default registry.

type Formatter

type Formatter interface {
	// Format converts the result to a formatted string.
	Format(result interface{}) (string, error)

	// Name returns the format name.
	Name() FormatType

	// TokenEstimate estimates the number of tokens in the output.
	// tokenizer can be "gpt4", "claude", "llama", or empty for default.
	TokenEstimate(result interface{}, tokenizer ...string) int

	// IsReversible returns whether the output can be parsed back to original.
	IsReversible() bool

	// SupportsStreaming returns whether the format supports streaming output.
	SupportsStreaming() bool

	// FormatStreaming writes formatted output to a writer (if supported).
	FormatStreaming(result interface{}, w io.Writer) error
}

Formatter formats query results into different output representations.

func GetFormatter

func GetFormatter(formatType FormatType) (Formatter, error)

GetFormatter returns a formatter from the default registry.

type GraphResult

type GraphResult struct {
	// Query is the original query.
	Query string `json:"query"`

	// FocusNodes are the main nodes of interest.
	FocusNodes []Node `json:"focus_nodes"`

	// Graph contains the full graph data.
	Graph GraphStats `json:"graph"`

	// KeyNodes are important nodes with annotations.
	KeyNodes []KeyNode `json:"key_nodes"`

	// Risk is the risk assessment.
	Risk RiskAssessment `json:"risk,omitempty"`
}

GraphResult represents a graph query result for formatting.

type GraphStats

type GraphStats struct {
	// NodeCount is the total number of nodes.
	NodeCount int `json:"node_count"`

	// EdgeCount is the total number of edges.
	EdgeCount int `json:"edge_count"`

	// Depth is the maximum graph depth.
	Depth int `json:"depth"`
}

GraphStats contains graph statistics.

type JSONFormatter

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

JSONFormatter formats results as full JSON.

func NewJSONFormatter

func NewJSONFormatter() *JSONFormatter

NewJSONFormatter creates a new JSON formatter.

func NewJSONFormatterCompact

func NewJSONFormatterCompact() *JSONFormatter

NewJSONFormatterCompact creates a JSON formatter without indentation.

func (*JSONFormatter) Format

func (f *JSONFormatter) Format(result interface{}) (string, error)

Format converts the result to JSON string.

func (*JSONFormatter) FormatStreaming

func (f *JSONFormatter) FormatStreaming(result interface{}, w io.Writer) error

FormatStreaming writes JSON to a writer.

func (*JSONFormatter) IsReversible

func (f *JSONFormatter) IsReversible() bool

IsReversible returns true - JSON has full fidelity.

func (*JSONFormatter) Name

func (f *JSONFormatter) Name() FormatType

Name returns the format name.

func (*JSONFormatter) SupportsStreaming

func (f *JSONFormatter) SupportsStreaming() bool

SupportsStreaming returns true - JSON can be streamed.

func (*JSONFormatter) TokenEstimate

func (f *JSONFormatter) TokenEstimate(result interface{}, tokenizer ...string) int

TokenEstimate estimates the number of tokens.

type KeyNode

type KeyNode struct {
	// Node is the base node information.
	Node

	// Callers is the number of callers.
	Callers int `json:"callers"`

	// Callees is the number of callees.
	Callees int `json:"callees"`

	// Flag indicates special status (e.g., "shared", "entry").
	Flag string `json:"flag,omitempty"`

	// Warning is a warning message about this node.
	Warning string `json:"warning,omitempty"`

	// Connections are connected nodes.
	Connections []Connection `json:"connections,omitempty"`
}

KeyNode represents an important node with additional info.

type MarkdownFormatter

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

MarkdownFormatter formats results as Markdown tables and lists.

func NewMarkdownFormatter

func NewMarkdownFormatter() *MarkdownFormatter

NewMarkdownFormatter creates a new Markdown formatter.

func (*MarkdownFormatter) Format

func (f *MarkdownFormatter) Format(result interface{}) (string, error)

Format converts the result to a Markdown string.

func (*MarkdownFormatter) FormatStreaming

func (f *MarkdownFormatter) FormatStreaming(result interface{}, w io.Writer) error

FormatStreaming writes Markdown to a writer.

func (*MarkdownFormatter) IsReversible

func (f *MarkdownFormatter) IsReversible() bool

IsReversible returns false - Markdown loses structure.

func (*MarkdownFormatter) Name

func (f *MarkdownFormatter) Name() FormatType

Name returns the format name.

func (*MarkdownFormatter) SetMaxRows

func (f *MarkdownFormatter) SetMaxRows(max int)

SetMaxRows sets the maximum number of table rows.

func (*MarkdownFormatter) SupportsStreaming

func (f *MarkdownFormatter) SupportsStreaming() bool

SupportsStreaming returns true.

func (*MarkdownFormatter) TokenEstimate

func (f *MarkdownFormatter) TokenEstimate(result interface{}, tokenizer ...string) int

TokenEstimate estimates the number of tokens.

type MermaidFormatter

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

MermaidFormatter formats results as Mermaid graph diagrams.

func NewMermaidFormatter

func NewMermaidFormatter(maxNodes int) *MermaidFormatter

NewMermaidFormatter creates a new Mermaid formatter. maxNodes limits the number of nodes for readability (default: 50).

func (*MermaidFormatter) Format

func (f *MermaidFormatter) Format(result interface{}) (string, error)

Format converts the result to a Mermaid diagram string.

func (*MermaidFormatter) FormatStreaming

func (f *MermaidFormatter) FormatStreaming(result interface{}, w io.Writer) error

FormatStreaming writes Mermaid diagram to a writer.

func (*MermaidFormatter) IsReversible

func (f *MermaidFormatter) IsReversible() bool

IsReversible returns false - Mermaid is visual only.

func (*MermaidFormatter) Name

func (f *MermaidFormatter) Name() FormatType

Name returns the format name.

func (*MermaidFormatter) SetDirection

func (f *MermaidFormatter) SetDirection(dir string)

SetDirection sets the graph direction (TD or LR).

func (*MermaidFormatter) SupportsStreaming

func (f *MermaidFormatter) SupportsStreaming() bool

SupportsStreaming returns false - needs full graph structure.

func (*MermaidFormatter) TokenEstimate

func (f *MermaidFormatter) TokenEstimate(result interface{}, tokenizer ...string) int

TokenEstimate estimates the number of tokens.

type Node

type Node struct {
	// ID is the unique node identifier.
	ID string `json:"id"`

	// Name is the display name.
	Name string `json:"name"`

	// Location is the file:line location.
	Location string `json:"location"`

	// Type is the symbol type (function, type, etc.).
	Type string `json:"type"`

	// Package is the package name.
	Package string `json:"package,omitempty"`
}

Node represents a code symbol node.

type OutlineFormatter

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

OutlineFormatter formats results as tree-style outlines.

func NewOutlineFormatter

func NewOutlineFormatter(unicode bool) *OutlineFormatter

NewOutlineFormatter creates a new outline formatter. If unicode is true, uses Unicode box-drawing characters.

func NewOutlineFormatterAutoDetect

func NewOutlineFormatterAutoDetect() *OutlineFormatter

NewOutlineFormatterAutoDetect creates an outline formatter with auto-detected charset.

func (*OutlineFormatter) Format

func (f *OutlineFormatter) Format(result interface{}) (string, error)

Format converts the result to an outline string.

func (*OutlineFormatter) FormatStreaming

func (f *OutlineFormatter) FormatStreaming(result interface{}, w io.Writer) error

FormatStreaming writes outline to a writer.

func (*OutlineFormatter) IsReversible

func (f *OutlineFormatter) IsReversible() bool

IsReversible returns false - outline loses some structure.

func (*OutlineFormatter) Name

func (f *OutlineFormatter) Name() FormatType

Name returns the format name.

func (*OutlineFormatter) SetASCIIMode

func (f *OutlineFormatter) SetASCIIMode(ascii bool)

SetASCIIMode sets whether to use ASCII characters.

func (*OutlineFormatter) SupportsStreaming

func (f *OutlineFormatter) SupportsStreaming() bool

SupportsStreaming returns true.

func (*OutlineFormatter) TokenEstimate

func (f *OutlineFormatter) TokenEstimate(result interface{}, tokenizer ...string) int

TokenEstimate estimates the number of tokens.

type ResultStats

type ResultStats struct {
	// NodeCount is the number of nodes.
	NodeCount int

	// RowCount is the number of data rows.
	RowCount int

	// EstimatedTokens is the estimated token count.
	EstimatedTokens int
}

ResultStats analyzes a result for capability checking.

func AnalyzeResult

func AnalyzeResult(result interface{}) ResultStats

AnalyzeResult extracts stats from a result for capability checking.

type RiskAssessment

type RiskAssessment struct {
	// Level is the risk level (low, medium, high).
	Level string `json:"level"`

	// DirectImpact is the number of directly affected files.
	DirectImpact int `json:"direct_impact"`

	// IndirectImpact is the number of indirectly affected files.
	IndirectImpact int `json:"indirect_impact"`

	// Warnings are specific risk warnings.
	Warnings []string `json:"warnings,omitempty"`
}

RiskAssessment contains risk information.

type TreeChars

type TreeChars struct {
	Branch   string // ├──
	LastItem string // └──
	Vertical string // │
	Arrow    string // →
	Warning  string // ⚠️
}

TreeChars defines characters for tree drawing.

Jump to

Keyboard shortcuts

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