Add --group-depth (directory rollup) and make --architecture's scan reproducible

[inth3shadows]

Why

--architecture draws one box per file, which is unreadable on any repo past a handful of files. --max-render was the only answer and it is lossy: it drops the least-busy files outright, taking every edge that touched them with it.

What

--group-depth <n> (--architecture only) rolls files up into their first n directory segments and draws those instead, summing the call weights of every file pair that collapses into the same group pair. Every cross-module call is preserved; calls that become intra-group are dropped, exactly as same-file calls already are, because this diagram is about coupling between modules rather than inside them.

Measured on a real repo (honeyslate, 200 symbols probed):

view	nodes
per-file (today)	20
--group-depth 1	2 (backend/, frontend/)
--group-depth 2	4, e.g. backend/alembic/ → backend/app/ weight 11

Design notes:

• The rollup runs after probing, never during — probes must stay file-exact (parseNodeCalls' expectedFile check, isTestRef, duplicate-name attribution all key off the real path), so this is a pure, unit-testable view over the same data rather than a second scan mode.
• Composes with --max-render (which then caps groups; renderTruncationNote says groups).
• Claims its own --embed marker id (codeshot:arch-d<n>), so the per-module picture cannot silently overwrite a committed per-file one. Unset --group-depth keeps the original codeshot:arch id, so existing docs are untouched.
• Rejected outside --architecture rather than silently ignored — a silently-dropped flag reads as "grouping applied" in exactly the diagram you would then trust.
• groupCollapseWarning distinguishes the two blank-diagram causes, which want opposite advice: one group (depth too coarse, go deeper) vs several groups with no calls between them (genuinely no cross-module coupling; deeper stays blank).

Reproducible enumeration. enumerateSymbols now sorts by (filePath, name) before the --max-symbols slice. codegraph's own result order for the enumeration query is unspecified, so a repo larger than the cap was probed on a different subset run to run — the same unchanged repo could render a different diagram, and a committed diagram guarded by --check could fail CI for no code reason. The sort is by code point, deliberately not localeCompare, whose implementation-default locale varies with the environment and the Node binary's ICU build and would reintroduce the same variance one layer down.

This makes the kept subset deterministic, not representative: it is a path-sorted prefix, so symbolBudgetWarning now says that unprobed late-path files can appear to call nothing when they do.

Verification

• npm test → 126 passed, 0 failed (+18), including 4 CLI-level tests run against this repo's real codegraph index.
• The exact CI diagram-gate commands → exit 0 on both committed diagrams; the sort did not perturb their structure.
• Live: test/run.js → render/callgraph.js (31) becomes test/ → render/ (31), test group still dashed.
• Dogfooded on honeyslate as above.

Docs updated in all three files, including the honest caveat that a grouped diagram's summed weights are legitimately lower than the per-file one's (that difference is intra-module traffic, not a lost edge).

🤖 Generated with Claude Code