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