feat(returns): opt-in per-group breakdown for report returns (--by-group) - #1841

Adds two ways to break `rledger report returns` down per group, alongside the
whole-scope TOTAL. Prior art (beangrow, fava-portfolio-summary) converges on
user-declared groups that bundle their income accounts so returns are
dividend-inclusive; this follows that, declared in the ledger rather than an
external config file (beangrow's anti-pattern).

- returns-group: metadata (default when present): tag `open` directives with
  `returns-group: "Name"`. A group's members are partitioned by account TYPE
  (via AccountTypes) — income-statement accounts form the group's income
  scope, balance-sheet accounts its investment scope — so a group that tags
  its dividend account reports a DIVIDEND-INCLUSIVE return. This is the
  beangrow group model, in-ledger.
- --by-account: one row per investment account with no income scope, a price
  return (ex-dividend); a quick per-holding view without tagging. Ignored when
  returns-group: groups are declared.

Both render per-group rows + a TOTAL in text/json/csv; with neither, the
report is unchanged (the whole-scope summary), so existing behavior and tests
are preserved. Refactored the computation into a shared compute_group helper.

Tests: metadata grouping (Tech dividend-inclusive 32.36% via its tagged income
account, Bonds 10%, TOTAL) and --by-account per-account rows. 9 returns
integration tests.

Deferred (per #1820): true per-commodity attribution within a single account,
and commodity-directive tagging.

…nciling residual

Reworks the #1820 per-group breakdown per deep-review findings on #1841.

- Drop `--by-account`: per-account auto-attribution is unsound (a dividend
  booked to a shared cash/income account cannot be attributed to one holding),
  and it wrongly booked the dividend as a contribution.
- Grouping is now opt-in behind `--by-group`; merely having `returns-group:`
  metadata no longer silently switches the output schema.
- Groups are built by classifying each tagged `open` against the whole scope,
  so they reconcile with the TOTAL: an out-of-scope tag (External / Equity /
  Liability) is ignored with a warning instead of being valued as a holding,
  and in-scope holdings left untagged collect into an `(ungrouped)` residual —
  every in-scope holding appears in exactly one row.
- A non-string `returns-group:` value warns instead of being silently dropped.

Tests: --by-group dividend-inclusive grouping, ungrouped residual +
TOTAL reconciliation, and default-is-single-summary (grouping opt-in).

The grouped text table appended a literal `%` to every rate column, so an
undefined MWR/TWR rendered as `n/a%` — reading like a real percentage and
inconsistent with the single-scope output, where the `%` hangs off the value.

Add `fmt_rate_pct` (value carries its own `%`; `None` -> `n/a`) for the text
row, matching render_single. CSV/JSON keep the bare numeric via `fmt_rate`.

…ge cases

Third-review polish on the --by-group breakdown:

- Income-only (empty-investment) group reported a fabricated 0.00% TWR: twr()'s
  unit-chaining returns Some(0.0) over an empty position. A scope that never held
  investment capital has no holding period to weight, so TWR is now None (n/a),
  matching the already-None MWR.
- Grouped text table: the =/- rules were 72 columns but the data/header rows are
  74, so the last column overhung the underline. Derive the rule width from the
  column layout.
- Sanitize control characters in a group label before the text table (a newline
  in a quoted returns-group value could split a row / inject a line). JSON and
  CSV already escape it.
- Warn when a group is named "TOTAL" (collides with the whole-portfolio row in
  text/CSV output; JSON keeps them structurally separate).

Tests: assert income-only TWR is null; a new cross-group prefix-overlap warning
test; and pin that a self-contained-warned group still renders on stdout.

…sum note

Round out the --by-group text output for parity and clarity (third-review UX
findings; warnings stay on stderr per the independent-sub-portfolio model):

- Add the Distributions column to the grouped text table, matching the
  single-scope output which already shows it (still under 80 columns).
- Footnote the table: "TOTAL is the whole portfolio, not the sum of the groups",
  so the TOTAL row below the rule isn't misread as a subtotal.

Test asserts both the Distributions column and the footnote are present.

…l-char labels

Fourth-review correctness findings:

- --by-group produced two incompatible schemas: with no in-scope returns-group
  metadata it fell back to the single-summary object (no groups/total keys), so a
  JSON/CSV consumer had to branch on ledger content. It now always emits the
  grouped schema (empty `groups` array plus `total`); the "no groups" notice
  stays on stderr.
- A returns-group value carrying a raw control byte (e.g. U+001B) was written raw
  inside the JSON string, because report's `json_escape` aliased `escape_string`
  (the beancount-source escaper, which only handles " \ \n \t \r). That is
  invalid JSON. Add a proper `escape_json` to rustledger-core (RFC 8259: \b \f
  and \uXXXX for the rest) and route report's json_escape through it — fixes every
  report JSON surface (holdings/accounts/income/journal/returns), not just groups.
- Broaden the text-label sanitizer to also neutralize U+2028/U+2029 (line and
  paragraph separators), which `is_control()` misses but a pager may honor.

Tests: escape_json unit test; --by-group-with-no-tags grouped-schema test; and a
control-char-label valid-JSON test.

Deferred (tool-wide, not returns-specific): CSV formula-injection neutralization
in the shared escape_csv; numeric-column overflow and Unicode display-width
alignment in fixed-width tables; the second per-group directive scan (-> #1832).

…ment

Fifth-review polish (both are follow-ups to the fourth-review fixes):

- The no-tags --by-group text output printed two horizontal rules back to back
  (the group-rows loop emits nothing, so the header rule and the pre-TOTAL rule
  were adjacent). Skip the pre-TOTAL separator when there are no group rows.
- Refresh the comment above the json_escape alias: it still described
  escape_string and claimed behavior-identity, but the alias now points at
  escape_json (which escapes additional control bytes). Corrected, with a note
  not to revert it (that would reintroduce invalid-JSON output).

Test asserts the no-groups text output has no adjacent rules.

…on display

Addresses Copilot review threads on #1841:

- Horizon consistency (the substantive one): build_groups iterated every `open`
  and first_shared_inscope_account scanned every transaction regardless of --end,
  while flow extraction/valuation are horizon-bounded. A historical report
  (--end in the past) therefore showed spurious all-zero rows for groups whose
  accounts open later, and could raise false self-containment warnings from
  post-horizon transfers. Both now skip directives dated after --end.
- Label sanitization: a `returns-group:` value is arbitrary user text; factor the
  control-char/U+2028/U+2029 neutralization out of truncate() into
  sanitize_display() and also apply it to the CSV label and the stderr warnings
  (so a label can't inject terminal escapes or extra lines on a human-facing
  surface). JSON keeps escape_json (lossless).

Test: a group whose account opens after --end does not appear in an earlier report.

…eturned

The build_groups warn closure was reformatted into block form when the
end_date argument lengthened the call; its eprintln! body needs a trailing
semicolon under the workspace -D warnings clippy gate.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013gJH7uBBF9Xw9et9QFRcsU

Copilot noted --by-group CSV was untested (only JSON/text were). Assert the
CSV header, a group data row, and the TOTAL row.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013gJH7uBBF9Xw9et9QFRcsU

…at handling

The comments claimed JSON escapes labels as \uXXXX (true only for C0 bytes;
U+2028/U+2029 stay raw) and that the CSV path escapes the raw label (it
sanitizes via sanitize_display). Corrected both to match the actual behavior.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013gJH7uBBF9Xw9et9QFRcsU

…n rustdoc

Empty result now emits the grouped shape (empty group list + total), not the
plain single summary; also document that grouping is end_date-bounded.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013gJH7uBBF9Xw9et9QFRcsU