searxng-mcp-go/docs/adr/011-max-content-runes-cli-only.md
XLion 9617a6318f
test: consolidate answer contract ownership (#563)
* test: consolidate answer contract ownership

* test: address answer ownership review
2026-08-12 00:33:45 +08:00

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.

  1. format.go:113 (root package) defined an unexported truncateRunes helper used by the CLI text formatter to bound result and infobox content fields.
  2. internal/searxng/deduplicate.go:47 defined a separate unexported truncateAtRunes helper 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

  1. One shared helper. Rune-safe truncation moves to a new exported helper searxng.TruncateRunes in internal/searxng/truncate.go. The searxng deduplication pass and the root CLI formatter both call it. The two prior local helpers (truncateRunes in format.go, truncateAtRunes in deduplicate.go) are removed.

  2. MaxContentRunes is 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 content rendering in formatResults;
    • the typed SearchResponse returned to JSON and MCP consumers is NOT truncated;
    • the truncation itself uses TruncateRunes.

    CONTEXT.md and docs/OUTPUT_FORMAT.md are updated for consistency. The docs/OUTPUT_FORMAT.md limits 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.

Rationale

  1. 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.go and internal/searxng/answer/truncate_test.go. The exported internal/searxng.TruncateRunes function remains a forwarding adapter, exercised through the formatter's user-visible call sites.
  2. 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.; calling searxng.TruncateRunes adds no new import edge.
  3. 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 of MaxContentRunes.
  4. 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.go defines the exported TruncateRunes(s string, maxRunes int) string helper. 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 in internal/searxng/answer/truncate.go. internal/searxng/truncate.go remains the exported forwarding adapter; parent coverage is limited to formatter integration, including Unicode truncation at the user-visible output seam.
  • format.go no longer defines truncateRunes. Both call sites in formatResults (infobox content and result content) call searxng.TruncateRunes.
  • internal/searxng/deduplicate.go no longer defines truncateAtRunes. answerPrefixMatch calls TruncateRunes for the 200-rune prefix and the lowercased 200-rune prefix.
  • MaxContentRunes is unchanged in value (4000). Its docstring is rewritten to clarify the CLI-only scope. CONTEXT.md is updated to match.
  • No changes to formatResults output, the golden fixture (golden_capture_test.go), or to the typed SearchResponse produced by normalizeResponse. 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.