Repository navigation
Architecture WS7: depgraph report-only summaries; upstream @statelyai/graph issues #3283
Description
Part of #3276.
Purpose
Give the analysis that produced #3276 a permanent home in the tooling, and push the rough edges we hit back upstream.
Required behavior
- Report-only fields in
pnpm depgraph(no gate behavior change): dominator summary for an entry file, zone-level SCC summary, and community/zone cohesion summary (the numbers the umbrella quotes: Louvain modularity of declared zones vs detected communities, per-zone cohesion). - File upstream issues against the
@statelyai/graphrepo for the 2.4.0 rough edges:getLouvainCommunitiesreturns ids butgetModularityrequires node objects and throws on ids;- docs name
toMermaid, package exportstoMermaidFlowchart; - Mermaid output does not escape ids like
(root); - importing
/dotfortoDOTrequires thedotparserpeer.
Include a minimal repro in each.
Done when
pnpm depgraphexposes the three summaries as report-only output with tests; gates unchanged.- Four upstream issues filed; links recorded in this issue.
Constraints
- Report-only: nothing in the layering gates may consume these fields until a decision issue says so.
- Follow
docs/agents/pull-requests.md(size budget, commit shape, validation).
Activity
thymikee commentedon Oct 7, 2026
Deliverable 1 is done (merged via #3285, stacked on #3275 which is also merged). Deliverable 2: filed 3 of the 4 upstream issues; the 4th claim didn't survive verification — see below rather than force a weak report.
All four claims were checked against
@statelyai/graph2.4.0 (what #3275/#3285 ship against) and the current latest, 2.5.1, to catch anything already fixed upstream.Filed:
getLouvainCommunitiesreturns bare ids,getModularitywantsCommunity<N>node objects. Still broken on 2.5.1, but the failure mode changed for the worse: 2.4.0 threw aTypeError; 2.5.0's "tolerates unknown ids" changelog entry made it stop throwing, but it now silently returns modularity0(a wrong answer, not caught) instead of raising anything.toMermaidFlowchartdoesn't escape node ids that collide with its own shape-delimiter grammar (e.g.(root)reads as a round-shaped node per the library's ownSHAPE_OPENERStable). Unchanged on 2.5.1./dotneeds the optionaldotparserpeer at runtime; that's documented insrc/formats/dot/README.md, but that file isn't published to npm (files: ["dist", "schemas"]) and the shipped JSDoc doesn't mention it either (its own@exampleeven importstoDOTfrom the wrong module). Unchanged on 2.5.1.Not filed — "docs name toMermaid, package exports toMermaidFlowchart": couldn't substantiate this one. I fetched the live stately.ai docs page, searched the repo's source, tests, and both the published and unpublished READMEs (including the mermaid format's own) — every reference I found already uses the correct
toMermaidFlowchart/toMermaidSequence/etc. names; there's no baretoMermaidanywhere I can find to point an issue at. Rather than file a bug report I can't back up, I'm flagging it here. If you have the specific page or commit where this was seen (maybe the docs site has since been corrected, or it was a different page), point me at it and I'll re-check and file if it still holds; otherwise I'd treat this one as resolved/moot and close #3283 with 3 of 4 filed.Not closing #3283 myself — leaving that to you.
thymikee commentedon Oct 8, 2026
Closing: both deliverables complete. (1) Report-only metrics landed via #3285 (merged, stacked on #3275). (2) Upstream follow-ups: 3 of 4 claims filed against @statelyai/graph 2.4.0 with repros (links in the earlier comment on this issue); the 4th claim was dropped after verification showed it did not hold — documented there rather than filed as a weak report.