* test: consolidate answer contract ownership * test: address answer ownership review
5.6 KiB
ADR-011: Share TruncateRunes Helper; MaxContentRunes Is CLI-Only
Status: Accepted Date: 2026-06-05
Context
Two rune-safe truncation helpers had drifted into the codebase, and the
MaxContentRunes constant's documented scope did not match the
implementation.
format.go:113(root package) defined an unexportedtruncateRuneshelper used by the CLI text formatter to bound result and infoboxcontentfields.internal/searxng/deduplicate.go:47defined a separate unexportedtruncateAtRuneshelper used by the answer/infobox deduplication prefix match.
Both helpers walked the input with for i := range s, sliced on the
rune boundary when the limit was reached, and returned the original
string unchanged for inputs that already fit. The behavior was
functionally equivalent; the duplication was structural and risked
subtle drift (e.g. one of them short-circuited on str == "", the
other let the empty-string case fall through the loop naturally).
Separately, MaxContentRunes was documented in
internal/searxng/constants.go:23 as "the maximum result content
length retained after normalization." That wording implied the limit
applies to the normalized SearchResponse that flows into both the
CLI formatter and the JSON / MCP path. In practice, the constant was
only consulted in format.go. The typed response surfaced to JSON
mode (--json) and MCP consumers was the full un-truncated
SearchResponse. CONTEXT.md:72 repeated the same wording without
flagging the rendering-vs-data-model distinction.
Decision
-
One shared helper. Rune-safe truncation moves to a new exported helper
searxng.TruncateRunesininternal/searxng/truncate.go. The searxng deduplication pass and the root CLI formatter both call it. The two prior local helpers (truncateRunesinformat.go,truncateAtRunesindeduplicate.go) are removed. -
MaxContentRunesis a CLI formatting limit, not a normalization limit. The constant stays where it is (internal/searxng/constants.go) because the helper's primary consumer is the formatter, and the searxng package is the natural home for a low-level string utility. The docstring is rewritten to spell out:- it bounds
contentrendering informatResults; - the typed
SearchResponsereturned to JSON and MCP consumers is NOT truncated; - the truncation itself uses
TruncateRunes.
CONTEXT.mdanddocs/OUTPUT_FORMAT.mdare updated for consistency. Thedocs/OUTPUT_FORMAT.mdlimits table already stated "CLI text mode only" and is left as the single place that documents the per-mode behavior; the constant's docstring now matches that table. - it bounds
Rationale
- Single source of truth. Two byte-identical helpers invited
drift. After the answer package extraction, the canonical implementation
and exhaustive contract tests live in
internal/searxng/answer/truncate.goandinternal/searxng/answer/truncate_test.go. The exportedinternal/searxng.TruncateRunesfunction remains a forwarding adapter, exercised through the formatter's user-visible call sites. - Helper lives with the lower-level package. The searxng package
has no dependencies on the root package, so the import direction
is clean. The root package already imports searxng for
MaxContentRunes,UnescapeIfNeeded,ExternalContentWarning, etc.; callingsearxng.TruncateRunesadds no new import edge. - Render-time limit, not data-model limit. Truncating before
formatting preserves the contract that JSON and MCP consumers
always see the full upstream text. If a future change needs
output-size bounding for JSON, that should be a separate
MaxJSONContentRunes(or similar) constant applied at JSON marshal time — not a silent broadening ofMaxContentRunes. - Docstring matters. The previous "retained after normalization" wording was wrong enough to mislead a future contributor into thinking normalization itself trims content. Explicitly naming the formatter and the modes avoids that trap.
Consequences
- New file
internal/searxng/truncate.godefines the exportedTruncateRunes(s string, maxRunes int) stringhelper. The package gains a trivial public surface, but the helper is well within the package's existing responsibility (string utilities for result processing). - The exhaustive unit matrix (empty / zero / negative limit, shorter /
exact / longer, ASCII, CJK, emoji, mixed, no-truncation) now lives in
internal/searxng/answer/truncate_test.go, alongside the canonical implementation ininternal/searxng/answer/truncate.go.internal/searxng/truncate.goremains the exported forwarding adapter; parent coverage is limited to formatter integration, including Unicode truncation at the user-visible output seam. format.gono longer definestruncateRunes. Both call sites informatResults(infobox content and result content) callsearxng.TruncateRunes.internal/searxng/deduplicate.gono longer definestruncateAtRunes.answerPrefixMatchcallsTruncateRunesfor the 200-rune prefix and the lowercased 200-rune prefix.MaxContentRunesis unchanged in value (4000). Its docstring is rewritten to clarify the CLI-only scope.CONTEXT.mdis updated to match.- No changes to
formatResultsoutput, the golden fixture (golden_capture_test.go), or to the typedSearchResponseproduced bynormalizeResponse. The CLI behavior and the JSON / MCP behavior are both unchanged. - If a future ADR decides to bound JSON / MCP output, it should
introduce a new constant rather than widen
MaxContentRunes.