feat(devkit): add dependency topology scanner script#361
Open
jensenojs wants to merge 2 commits intosudo-tee:mainfrom
Open
feat(devkit): add dependency topology scanner script#361jensenojs wants to merge 2 commits intosudo-tee:mainfrom
jensenojs wants to merge 2 commits intosudo-tee:mainfrom
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a Python-based static dependency topology scanner for the lua/opencode/** Lua modules, with configurable layer/group policy rules and optional HTML visualization to support architectural cleanup discussions.
Changes:
- Introduces a topology strategy file (
topology.jsonc) defining layers/groups and forbidden dependency directions. - Adds scanner CLI (
scan/diff) plus core analysis + graph utilities for SCC/cycle and policy-violation detection. - Adds an interactive HTML renderer for clustered dependency visualization, and documents the tool for agents/contributors.
Reviewed changes
Copilot reviewed 7 out of 8 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| scripts/dependency-topology/topology.jsonc | Defines layer groups and policy rules for dependency analysis. |
| scripts/dependency-topology/scan_topology.py | CLI entrypoint for scan/diff, emits JSON or HTML output. |
| scripts/dependency-topology/scan_analysis.py | Implements grouping, policy evaluation, and scan/diff payload construction. |
| scripts/dependency-topology/graph_utils.py | Builds module graph from require() usage and provides SCC/cycle helpers. |
| scripts/dependency-topology/html_renderer.py | Renders interactive dagre-d3 HTML with clustering and violation styling. |
| scripts/dependency-topology/AGENTS.md | Local documentation for using the topology scanner. |
| AGENTS.md | Repo-level guidance referencing the topology scanner for architecture discussions. |
| .gitignore | Ignores topology tool artifacts (pycache + HTML output). |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Static analysis tool for Lua codebase architectural layering. - scan_topology.py: CLI entry (scan / diff subcommands) - scan_analysis.py: core analysis, group matching, policy violation detection - graph_utils.py: pure graph algorithms (Tarjan SCC, back-edges, degree) - html_renderer.py: interactive dagre-d3 HTML visualization with cluster expand/collapse, violation highlighting, SCC marking - topology.jsonc: 5-layer group definitions with English comments explaining each module placement and REVIEW notes for debatable calls scan --json produces agent-friendly output: health summary (cycles/violations/ungrouped with verdicts) cycles with severity, members_by_layer, example_cycle path, back_edges violations grouped by rule with full edge lists group_coverage confirming 0 ungrouped modules
- graph_utils: clear error message on invalid git ref - scan_analysis: remove unused imports (degree, largest_scc_size) - html_renderer: defensive isinstance guard in match_group; fix expanded cluster edges — children now show actual connections via rawEdges projection instead of appearing isolated - scan_topology: eliminate duplicate graph/SCC computation in cmd_scan; smart diff default (dirty worktree → HEAD vs worktree, clean → HEAD~1 vs HEAD); expand diff human output with SCC changes, fixed/new violations per edge - add requirements.txt declaring json5 dependency - AGENTS.md: document diff default behavior and ref syntax
jensenojs
force-pushed
the
feat/dependency-topology-tool
branch
from
f94a0f8 to
0d1bc13
Compare
jensenojs
changed the title
Contributor
Author
|
Here is an example of usage, 
|
Owner
|
Thanks for the script I will have a look at it soon. I have a pretty busy week ahead, so it might take a couple of days before I can test it properly |
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.
During the process of splitting core.lua, the code does not seem to have become clearer. #360
After running some static checks, it was found that after deleting core.lua, the cycle dependency graph did not decrease but instead increased—the largest strongly connected component expanded from 34 modules to 36 modules. Modules such as services.session_runtime took over the central position originally held by core and merged into the main cycle.
#360 is heading in the right direction, but what it does is more like exposing the issues that were originally hidden in core.lua rather than resolving them.
We’ve been refactoring without a global view of the dependency graph, any cleanup we did is just hitting a local optimum—we might be fixing one spot while making the overall structure worse.
This PR provides a tool, and I hope it serves as a good start
Current baseline (upstream/main): 4 SCCs, with the largest cycle containing 34 modules.
Also worth mentioning is that I vibed a topology.jsonc, which roughly aligns with my previous architectural design diagram, targeting a layered architecture (5 layers: entry / dispatch / capabilities / infrastructure / foundation) and specifying which directional dependencies are prohibited (this is a very rough, very rough direction). #322 (comment)
After parsing the topology of the call chain, this part of the rules will be further used to evaluate the rationality of the topology itself.
I'm much less familiar with the project than you are, so I need you to evaluate it @sudo-tee . Once you adjust this jsonc, you'll have a tool to check whether the project's current shape matches your expectations and where it diverges. I can then make further project changes guided by that assessment.