analyze: replace --by-name by --group-by

[ThomasWaldmann]

--by-name was already a grouping, with the keys hardwired to name:

archives_per_name[info.name] += 1
owner_of = {name: i + 1 for i, name in enumerate(names)}

Two problems with that:

It is wrong in a shared repository. Archive series names are not unique across hosts, so two
machines backing up a home series collapse into one row. That row's exclusive size is the combined
cost of two unrelated data sets, attributable to neither, and the report's own claim — "deleting all
archives of that name would free them" — silently becomes a statement about both hosts' data.

It no longer matches prune. analyze's headline number is "what would I free by dropping this
row", which is only actionable if the row is the unit prune actually operates on. Since #10291 that
unit is (name, host), while analyze's was (name) — they stopped lining up in exactly the repositories
where the question is worth asking.

The change

--by-name is replaced by --group-by KEYS, taking the same comma-separated archive attributes as
prune (name, host, user, tags) and the same archive_group_key(). --group-by name is the
previous behaviour. As before, giving the option selects the decomposition mode and it cannot be
combined with archive filters, since the shared and unreferenced rows need the repository-wide view.
An empty --group-by "" is rejected: for prune "one group" is meaningful, here it would be a single
row covering the whole repository, which says nothing.

There is a second, less obvious payoff. Grouping by more attributes moves chunks from the group rows
into the shared row, where they belong: if two hosts back up identical content, --group-by name
reports it as exclusive to that name, while --group-by name,host correctly shows that deleting
either host's archives alone would not free it. The old report overstated per-name reclaimable space.

Text report row labels change from the bare name to the formatted group key, the same one prune and
repo-list print:

name                                  archives     source     stored
alpha                                        2    1.00 kB        ...
(shared by 2+ names)                              1.00 kB        ...

becomes

group                                 archives     source     stored
name='home', host='host1'                    1    1.00 kB        ...
(shared by 2+ groups)                             1.00 kB        ...

JSON

Changed without keeping compatibility, as requested:

• by_name → by_group
• its names list → groups
• each entry's name string → a group object mapping each grouped-by attribute to this group's
  value, e.g. {"name": "home", "host": "host1"}
• new group_by key listing the attributes that were grouped by

docs/internals/frontends.rst is updated to match. MAX_NAMES became MAX_GROUPS (same 2^18−2
limit, which now bounds distinct groups — more attributes mean more groups, so the guard earns its
keep).

Tests

• test_analyze_group_by_name — the old --by-name test, now asserting the group-labelled rows
• test_analyze_group_by_name_and_host — new: both hosts use a home series; --group-by name
  shows one group with everything exclusive to it, --group-by name,host shows two groups with the
  common file correctly moved into the shared row
• test_analyze_group_by_rejects_filters, test_analyze_group_by_needs_a_key
• test_analyze_json_group_by — the new JSON shape, including group_by and the group objects

Full test suite: 2935 passed, 986 skipped. ruff check clean.

Worth a CHANGES entry as a breaking change, since --by-name shipped in 2.0.0b23 and the JSON key
changes with it:

• analyze: replaced --by-name by --group-by, which decomposes the repository by the same
  archive attributes borg prune --group-by groups by. --group-by name is the previous
  behaviour. The JSON output's by_name key became by_group.

[codecov]

Codecov Report

❌ Patch coverage is 94.28571% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 87.66%. Comparing base (0adbb7a) to head (c9493ed).
⚠️ Report is 3 commits behind head on master.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
src/borg/archiver/analyze_cmd.py	94.28%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##           master   #10301   +/-   ##
=======================================
  Coverage   87.65%   87.66%           
=======================================
  Files         103      103           
  Lines       18702    18717   +15     
  Branches     2877     2881    +4     
=======================================
+ Hits        16393    16408   +15     
+ Misses       1609     1607    -2     
- Partials      700      702    +2     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.