You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 136eb63
Browse filesBrowse the repository at this point in the historyBrowse files
feat(depgraph): dominator, zone-SCC, and cohesion report summaries (#3285)
* feat(depgraph): add dominator, zone-SCC, and cohesion report summaries
Adds three report-only fields to `pnpm depgraph` nothing in scripts/layering
or scripts/check-affected reads: a dominator-tree summary of one entry's
eager-load closure over value edges (default src/daemon.ts, overridable with
--dominator-entry), zone-level strongly connected components over value zone
pairs, and Louvain community detection scored against declared zones with
getModularity, plus a per-zone cohesion share. Each reproduces the numbers
#3276 quotes from the earlier ad hoc analysis (621/1837 eager files, the
maestro/provider-webdriver dominator branches, the 9-zone cycle, 0.373 vs
0.564 modularity, and the five lowest per-zone cohesion shares) against the
current tree.
getModularity wants Community<N> (full node objects) but getLouvainCommunities
returns bare ids; computeCohesionSummary maps ids back onto the graph's own
nodes rather than working around it at every call site.
Co-Authored-By: Claude Sonnet 5 <[email protected]>
* fix(depgraph): tighten report assertions and empty-flag handling
Review findings on #3285:
- model.test.ts asserted the SCC/modularity summary lines with shape-only
regexes that accepted any count or score, so a CLI line inconsistent with
the JSON it was derived from still passed. Compare against the exact
payload values instead (planted a wrong modularity value to confirm the
test now fails without the fix).
- flagValue returned an empty string for `--out ""` / `--dominator-entry ""`
verbatim, which bypassed the `?? <default>` fallback (only nullish values
trigger it) and resolved --out to the current directory, crashing the
write with EISDIR instead of falling back like a missing value does. Fixed
at the shared helper, with a regression test for both flags (confirmed
both fail against the prior flagValue).
- README overstated dominatorSummary.bottlenecks as covering "every
reachable file"; the entry itself is excluded by construction.
- Clarified the ALL_EDGES doc comment: computeZoneSccSummary builds its own
value-only zone graph and never reads this constant, only
computeCohesionSummary does.
Co-Authored-By: Claude Sonnet 5 <[email protected]>
---------
Co-authored-by: Claude Sonnet 5 <[email protected]>
Copy file name to clipboardExpand all lines: scripts/depgraph/README.md
+33-2Lines changed: 33 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -107,8 +107,10 @@ Extraction stays with the layering gate; traversal does not. `import-graph.ts` t
107
107
edges into a [`@statelyai/graph`](https://stately.ai/docs/packages/graph) graph filtered to the
108
108
edge kinds a question needs (value for evaluation order, value + dynamic for what a handler can
109
109
run), and the report and `affected` query use its BFS, postorder, and transitive reduction rather
110
-
than hand-rolled walks. The library also carries centrality, community, dominator, and layout
111
-
algorithms; reach for them in a throwaway probe before writing a new traversal here.
110
+
than hand-rolled walks. `structure-summary.ts` additionally uses its dominator tree, strongly
111
+
connected components, and Louvain community detection — see "Structural summaries" below. The
112
+
library also carries centrality and layout algorithms; reach for them in a throwaway probe before
113
+
writing a new traversal here.
112
114
113
115
## What the JSON carries
114
116
@@ -122,6 +124,35 @@ algorithms; reach for them in a throwaway probe before writing a new traversal h
122
124
dynamic. Flags bitfield: `1` spine back-edge, `2` target also reachable at distance >= 2, `4` type-only
123
125
inversion.
124
126
-`cycles[]` — each with `kind` (`value` / `type` / `dynamic`) and its node path.
127
+
-`dominatorSummary`, `zoneSccSummary`, `cohesionSummary` — see "Structural summaries" below.
128
+
129
+
## Structural summaries (report-only)
130
+
131
+
`scripts/depgraph/structure-summary.ts` adds three fields nothing in `scripts/layering/` or
132
+
`scripts/check-affected/` reads. They are the numbers workstream 7 of #3276 asked to keep a
133
+
permanent home in the tooling, not a gate.
134
+
135
+
-**`dominatorSummary`** — the dominator tree of one entry's eager-load closure over VALUE edges
136
+
only (dynamic imports are a deliberate cold-start seam, so they never join the closure).
137
+
`reachableFiles` is the eager closure size; `bottlenecks` ranks every reachable non-entry file
138
+
by how many files become unreachable if it disappeared — the size of the branch moving it
139
+
behind `import()` would cut. Defaults to `src/daemon.ts`; override with
140
+
`pnpm depgraph --dominator-entry <path>`.
141
+
-**`zoneSccSummary`** — strongly connected components of the zone graph, built from VALUE zone
142
+
pairs only (`zoneEdges` entries with `valueCount > 0`), the same edge kind R4 keeps acyclic at
143
+
file level. R4 is file-level; nothing stops a loop from closing once files collapse into zones —
144
+
the guardrail gap workstream 4 of #3276 names. A component with `size > 1` is a live cycle.
145
+
-**`cohesionSummary`** — Louvain communities (`getLouvainCommunities`, mixing every edge kind
146
+
since community detection treats the graph as undirected) versus declared zones, scored with
147
+
`getModularity`, plus a per-zone `cohesionShare`: the share of a zone's files that land in its
148
+
largest detected community. Low values are where the folder partition cuts across a cluster the
0 commit comments