Interactive module graph viewers - #82375
Open
crisptrutski wants to merge 3 commits into
Open
Conversation
`./bin/mage modules-tree --html` writes a single page with three views of the module config: the tree, a coupling ranking, and a dependency graph around focused modules. `dev.module-explorer/open!` builds the same page in a dev REPL with namespace-level edges, so the graph can show which API namespaces each consumer uses. The graph replaces dev.module-viz and its Jetty server. Source paths, stats and teams go through the shared resolver, so nested and renamed modules report correctly. module-team moves into hooks.common.modules.
crisptrutski
marked this pull request as ready for review
September 11, 2026 20:30
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Part of BEGUILD-18: Module system improvements.
Why
The backend module configuration now contains 209 modules, including 81 whose namespace prefix does not match the module name. The existing inspection tools each cover only part of that system:
./bin/mage modules-treeshows the correct hierarchy, but not module boundaries or dependencies.dev.module-vizshows dependencies, but derives source paths, line counts, and team ownership from module names. That gives incorrect results for custom namespace prefixes and nested modules. It can also count a child module's files as part of its parent.This PR adds one explorer that combines the hierarchy and dependency data, backed by the shared module resolver. The existing text tree remains available for quick terminal use.
What changed
The explorer has three views:
:uses :anyunresolved.There are two ways to build it:
./bin/mage modules-tree --html --output modules.html(dev.module-explorer/open!)dev.deps-graphOther changes:
.api,.core, and.initnamespaces when:apiis omitted.:uses :anymodules remain explicit instead of being expanded into a dependency on every module. The REPL entry point replaces that unknown set with dependencies observed in the source scan.dev.module-vizHTML, Clojure namespace, and Jetty server have been removed. The explorer embeds its data in one HTML file and runs entirely in the browser.The Tree and Hotspots views work offline. The Graph view loads Cytoscape and its layout libraries from
unpkg.comwhen opened.How to verify
Generate and open the explorer:
In Tree, select a nested module with a custom prefix, such as
query-processor.cache-backend. Confirm that its source link and statistics belong to that module rather thanquery-processor.Switch to Hotspots and rank by dependents, dependencies, and total coupling.
Switch to Graph, focus a module, change the hop count, and filter or hide neighboring modules.
From a dev REPL, run
(dev.module-explorer/open!). Expand a module in Graph and confirm that incoming edges identify the API namespaces used by each consumer.Use
--no-statswith the Mage command when a faster snapshot is more useful than source metrics.Test coverage
The updated tests cover module tree paths, enterprise nesting, custom prefix resolution, effective API defaults, inherited team ownership, unrestricted and observed dependencies, URL-state round trips, Git failures, per-file module assignment, and safe embedding of module data in the generated page.