fix: group cut connections by file on explain for high-degree nodes (#2009)

[Yyunozor]

Summary

graphify explain "<node>" on a high-degree node sorts connections by neighbor degree, shows the top 20, and appends a bare ... and N more for the rest — no file, no direction, no way to tell what was cut. The exact question explain exists to answer ("who calls this, what's the impact?") goes unanswered for the majority of callers on any node above degree ~20, and the fallback is a repo-wide grep — what the graph was meant to replace.

Reproduction

A node with 30 callers spread across 3 files (10 each):

$ graphify explain log_helper
...
Connections (30):
  <-- caller_0() [calls] [EXTRACTED] app/handlers/email.py:L10
  ... (19 more shown) ...
  ... and 10 more

The last 10 callers vanish with zero indication of where they live, even though all 3 files are still meaningfully represented in the cut set.

Root cause

cli.py's explain handler: the connections[:20] slice, followed by a bare ... and {len(connections) - 20} more count — no aggregation of any kind on the remainder.

Fix

Top-20 list and ordering unchanged (verified with a byte-for-byte regression test for nodes at/under the cutoff). Past it, cut connections are grouped by (direction, source_file) with counts, sorted by count descending:

  ... and 10 more
  Grouped by file:
    <-- lib/workers/queue.py: 4 connections
    <-- app/handlers/email.py: 3 connections
    <-- app/jobs/retry.py: 3 connections

The aggregation itself is capped at 20 files with its own ... and N more files line, so a pathological remainder (hundreds of distinct files) can't reproduce the same problem one level down.

Scope note

The issue also proposes --callers --all / --group-by=dir flags and untruncated output behind a flag — a larger, more opinionated surface (flag naming, grouping level, pagination) than the literal complaint needs. Left for a follow-up; the default output no longer hides the answer either way.

Validation

Four regression tests in tests/test_explain_cli.py: unchanged truncation notice, grouped-by-file counts summing back to the cut total (no silent loss), a no-op check at/under the cutoff, and a boundary check pinning it at exactly 20 vs. 21 connections.

pytest -q
3350 passed, 166 skipped, 13 failed

Parent commit (e32c9f4), same env: 3346 passed — delta is exactly these 4 tests, same 13 pre-existing failures both sides (missing optional tree-sitter-hcl/ollama extras, a built-wheel fixture — unrelated). ruff check clean. test_serve.py (#2080's tests) passes unchanged, 126/126.

[Yyunozor]

Landed on v8 as 0ef452c, with the deterministic tie-break follow-up in 4c759b6 — closing as superseded. Thanks!