feat(explain): add --limit so connections past the top 20 are readable

[lucadepascale]

What

graphify explain prints the 20 most connected neighbours and then stops. This adds --limit N (and --limit=N) to raise that cut, with --limit 0 printing every connection.

The default stays 20, so output is byte-identical when the flag is absent.

Why

#2009 already improved what happens after the cut, by grouping the remainder per file. That answers where the rest are, but not what they are — and on a hub node the callers themselves stay unreachable from the CLI, so the only way to read them is the repo-wide grep the tool exists to avoid.

The MCP server never had this problem: it has a per-call token_budget. So this is purely about interactive use.

Details

• --limit also bounds the grouped-by-file list, which carried the second hardcoded 20.
• Non-integer and negative values exit 1 with a message, matching how --top and --max-examples already behave.
• The "... and N more" line now names the flag, so the next person does not have to find it in --help.

Tests

Six new tests in tests/test_explain_cli.py, on a fixture hub node with 25 (and 40) callers:

• the default cut is unchanged at 20 with ... and 5 more
• --limit 25 shows all 25 and stops summarizing
• --limit=0 shows all 40 and prints no grouped section
• --limit 3 shows 3 and still summarizes the remaining 22 by file
• a non-integer and a negative value each exit 1 with the right message

tests/test_explain_cli.py is green (20 passed).

Note unrelated to this change

On Windows, tests/test_build.py::test_semantic_rekey_relative_vs_absolute_source_file fails on a clean checkout of v8 (verified by stashing this branch's changes). It looks like a path-separator assumption rather than anything to do with explain; happy to open a separate issue if it is not already known.

[graphify-labs]

Graphify reviewed this change.

Worth a look — the grounded gate found no coupling regressions or blocking issues, but 1 advisory finding(s) below merit a look before merge.

---

Graphify review — findings

This PR adds a --limit N option (also accepting --limit=N) to the graphify explain CLI command, letting users control how many connections are printed before the grouped-by-file summary, with 0 meaning print all and a default of 20. The change introduces a limit-parsing helper with validation for non-integer and negative values, applies the limit to both the connection list and the grouped-by-file summary, and updates the usage string and "more" message. A new test suite covers the default behavior, raising/lowering the cut, the 0 case, and the error paths, and the CHANGELOG notes the addition.

Worth a look

• --limit without a value is silently ignored — graphify/cli.py:1465 · Escalate · medium
  • agreed by 2 of 2 members but NOT verified (no proof, no reproducing execution) — consensus is not a verdict; needs human review

Analysis details — impact, health, verification

Impact & health

Graphify review

Impact — 416 functions depend on the 270 functions this change touches.

Health — this change adds coupling hotspots:

• worse: dispatch_command() — 2 callers, 120 callees

Verification — 416 functions in the blast radius were not formally verified this run (proofs are advisory here).

Gate & verification

graphify gate

PASS — objectively clean (no health regressions, tests not run — proofs not run this pass (advisory)). Grounded, not self-assessed.

Advisory (not blocking):

• verification_scope: 387 function(s) in the blast radius were not formally verified this run

· 1 grounded finding(s) anchored inline below; 1 more finding(s) on lines outside this diff (see the check run).

[graphify-labs]

--limit without a value is silently ignored — agreed by 2 of 2 members but NOT verified (no proof, no reproducing execution) — consensus is not a verdict; needs human review

Graphify suggests a fix:

Suggested change

	elif a == "--limit" and i + 1 < len(args):
	limit = _explain_limit(args[i + 1])
	elif a.startswith("--limit="):
	elif a == "--limit":
	if i + 1 >= len(args):
	print("error: --limit requires a value", file=sys.stderr)
	sys.exit(1)
	limit = _explain_limit(args[i + 1])
	elif a.startswith("--limit="):