Documentation
¶
Index ¶
- Constants
- Variables
- func Format(result interface{}, formatType FormatType) (string, error)
- func GetSchema() map[string]string
- type CompactFormatter
- func (f *CompactFormatter) Format(result interface{}) (string, error)
- func (f *CompactFormatter) FormatStreaming(result interface{}, w io.Writer) error
- func (f *CompactFormatter) IsReversible() bool
- func (f *CompactFormatter) Name() FormatType
- func (f *CompactFormatter) SupportsStreaming() bool
- func (f *CompactFormatter) TokenEstimate(result interface{}, tokenizer ...string) int
- type Connection
- type FormatCapability
- type FormatMetadata
- type FormatRegistry
- func (r *FormatRegistry) AutoSelectFormat(result interface{}, tokenBudget int) FormatType
- func (r *FormatRegistry) Format(result interface{}, formatType FormatType) (string, error)
- func (r *FormatRegistry) GetCapability(formatType FormatType) (FormatCapability, bool)
- func (r *FormatRegistry) GetFormatter(formatType FormatType) (Formatter, error)
- func (r *FormatRegistry) GetMetadata(formatType FormatType) (FormatMetadata, error)
- func (r *FormatRegistry) ListFormats() []FormatType
- func (r *FormatRegistry) Register(formatType FormatType, formatter Formatter)
- func (r *FormatRegistry) ValidateCapability(result interface{}, formatType FormatType) error
- type FormatType
- type Formatter
- type GraphResult
- type GraphStats
- type JSONFormatter
- func (f *JSONFormatter) Format(result interface{}) (string, error)
- func (f *JSONFormatter) FormatStreaming(result interface{}, w io.Writer) error
- func (f *JSONFormatter) IsReversible() bool
- func (f *JSONFormatter) Name() FormatType
- func (f *JSONFormatter) SupportsStreaming() bool
- func (f *JSONFormatter) TokenEstimate(result interface{}, tokenizer ...string) int
- type KeyNode
- type MarkdownFormatter
- func (f *MarkdownFormatter) Format(result interface{}) (string, error)
- func (f *MarkdownFormatter) FormatStreaming(result interface{}, w io.Writer) error
- func (f *MarkdownFormatter) IsReversible() bool
- func (f *MarkdownFormatter) Name() FormatType
- func (f *MarkdownFormatter) SetMaxRows(max int)
- func (f *MarkdownFormatter) SupportsStreaming() bool
- func (f *MarkdownFormatter) TokenEstimate(result interface{}, tokenizer ...string) int
- type MermaidFormatter
- func (f *MermaidFormatter) Format(result interface{}) (string, error)
- func (f *MermaidFormatter) FormatStreaming(result interface{}, w io.Writer) error
- func (f *MermaidFormatter) IsReversible() bool
- func (f *MermaidFormatter) Name() FormatType
- func (f *MermaidFormatter) SetDirection(dir string)
- func (f *MermaidFormatter) SupportsStreaming() bool
- func (f *MermaidFormatter) TokenEstimate(result interface{}, tokenizer ...string) int
- type Node
- type OutlineFormatter
- func (f *OutlineFormatter) Format(result interface{}) (string, error)
- func (f *OutlineFormatter) FormatStreaming(result interface{}, w io.Writer) error
- func (f *OutlineFormatter) IsReversible() bool
- func (f *OutlineFormatter) Name() FormatType
- func (f *OutlineFormatter) SetASCIIMode(ascii bool)
- func (f *OutlineFormatter) SupportsStreaming() bool
- func (f *OutlineFormatter) TokenEstimate(result interface{}, tokenizer ...string) int
- type ResultStats
- type RiskAssessment
- type TreeChars
Constants ¶
const CompactSchemaName = "trace/compact/v1"
CompactSchemaName is the schema identifier.
const CompactSchemaVersion = "1"
CompactSchemaVersion is the current compact schema version.
const FormatVersion = "1"
FormatVersion is the current version of the format specification.
Variables ¶
var ASCIIChars = TreeChars{
Branch: "|-- ",
LastItem: "`-- ",
Vertical: "| ",
Arrow: "->",
Warning: "[!]",
}
ASCIIChars are the ASCII fallback characters.
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.
var DefaultRegistry = NewFormatRegistry()
DefaultRegistry is the default format registry.
var ErrFormatNotSupported = errors.New("format not supported")
ErrFormatNotSupported is returned when a format type is not supported.
var ErrResultTooLarge = errors.New("result exceeds format capabilities")
ErrResultTooLarge is returned when a result exceeds format capabilities.
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.
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.
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.