Documentation
¶
Overview ¶
Package outputfilter implements an RTK-style declarative output-compression engine. It maps a shell command to a TOML-defined filter and applies an 8-stage line-oriented pipeline that strips noise from verbose tool output before it reaches the LLM, reducing token consumption.
Design principles ported from RTK (https://github.com/rtk-ai/rtk):
- Fail-safe: any error returns the raw output unchanged; the engine never blocks or drops a command's result.
- Deterministic: the first filter whose match_command matches wins; filters loaded earlier (project/user overrides) take precedence over built-ins.
- Transparent: only the text shown to the LLM is altered, never exit codes.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
Engine holds an ordered list of compiled filters plus the native structured parsers. Parsers are consulted before filters; within filters, the first match wins (filters added first have higher precedence).
func Load ¶
Load builds an engine from the embedded defaults plus any extra TOML files in paths. Earlier paths take precedence over later ones, and all paths take precedence over the embedded defaults (first match wins). Missing files are skipped silently; malformed files contribute an error but never abort the build, preserving the fail-safe contract.
func LoadDefaults ¶
LoadDefaults returns an engine populated only with the embedded built-in filters. It never returns nil; a parse error yields an empty engine.
func LoadFileFilters ¶
LoadFileFilters builds an engine from a single TOML filter file WITHOUT the embedded defaults, so authors can test exactly the filters declared in their file. It is fail-safe like Load: a malformed filter contributes an error but never aborts the rest. Native parsers are not seeded — only declarative filters carry inline tests.
func New ¶
func New() *Engine
New returns an engine with only the built-in native parsers (no filters).
func (*Engine) Apply ¶
Apply compresses output for command. It first tries the native structured parsers (test runners, linters, compilers) in precedence order; a parser that produces a Full or Degraded result wins. Otherwise it falls back to the first matching TOML filter and runs its 8-stage pipeline. It returns the compressed text, whether anything was applied, and the matched parser/filter name. If nothing matches (or a parser only manages passthrough), output is returned unchanged with applied=false. Apply never panics and never drops output.
func (*Engine) RunInlineTests ¶
func (e *Engine) RunInlineTests() []FilterTestResult
RunInlineTests runs every filter's inline [[tests]] in declaration order and returns one FilterTestResult per case. It never panics; a filter that reports failure on its input yields a failed result with Err set.
type Filter ¶
type Filter struct {
Description string `toml:"description"`
MatchCommand string `toml:"match_command"`
StripANSI bool `toml:"strip_ansi"`
StripLinesMatching []string `toml:"strip_lines_matching"`
KeepLinesMatching []string `toml:"keep_lines_matching"`
Replace []ReplaceRule `toml:"replace"`
MatchOutput []MatchRule `toml:"match_output"`
TruncateLinesAt int `toml:"truncate_lines_at"`
HeadLines int `toml:"head_lines"`
TailLines int `toml:"tail_lines"`
MaxLines int `toml:"max_lines"`
OnEmpty string `toml:"on_empty"`
Tests []FilterTest `toml:"tests"`
// contains filtered or unexported fields
}
Filter is a single declarative output filter ([filters.<name>] in TOML).
type FilterTest ¶
type FilterTest struct {
Name string `toml:"name"`
Input string `toml:"input"`
Expected string `toml:"expected"`
}
FilterTest is an inline self-test embedded in a filter definition. The test runner feeds Input through the filter and asserts the result equals Expected.
type FilterTestResult ¶
type FilterTestResult struct {
Filter string // owning filter name
Test string // the test's `name` (may be empty)
Passed bool
Got string // actual pipeline output
Expected string // declared expected output
// Err is non-empty when the filter reported a hard failure on the input
// (its pipeline short-circuited to raw); the case is counted as failed.
Err string
}
FilterTestResult is the outcome of running one inline [[filters.<name>.tests]] case through its owning filter's pipeline. Trailing newlines are ignored when comparing Got against Expected (the pipeline normalises them).
type MatchRule ¶
type MatchRule struct {
Pattern string `toml:"pattern"`
Message string `toml:"message"`
Unless string `toml:"unless"`
// contains filtered or unexported fields
}
MatchRule short-circuits the whole pipeline: if Pattern matches the entire output blob (and the optional Unless pattern does not), the filter returns Message instead of the output.
type Parser ¶
type Parser interface {
// Name identifies the parser (used in debug/metadata).
Name() string
// Match reports whether the parser applies to the command.
Match(command string) bool
// contains filtered or unexported methods
}
Parser is a native, code-driven output compressor for commands whose output is structured (test runners, linters, compilers) and not well served by the line-oriented TOML pipeline. Parsers take precedence over TOML filters: when a parser matches a command, its result is used (unless it degrades all the way to passthrough).
Each parser implements RTK's 3-tier degradation internally: Full (structured) → Degraded (regex) → Passthrough (raw). This keeps the contract fail-safe — parse never returns an error, only a tier.
type ReplaceRule ¶
type ReplaceRule struct {
Pattern string `toml:"pattern"`
Replacement string `toml:"replacement"`
// contains filtered or unexported fields
}
ReplaceRule is a single chained regex substitution applied per line.
Source Files