Dependency Graph

The graph command visualizes and analyzes dependency relationships across the monorepo workspace. It detects cycles, enforces architectural layering rules, and generates graph visualizations in multiple formats.

Subcommands

graph visualize

Generates a visualization of the workspace dependency graph:

# Text output to stdout (default)
dart run monorepo_toolkit graph visualize

# DOT format for Graphviz
dart run monorepo_toolkit graph visualize --format dot --output graph.dot

# Mermaid diagram for Markdown
dart run monorepo_toolkit graph visualize --format mermaid --output graph.md

# JSON for programmatic use
dart run monorepo_toolkit graph visualize --format json --output graph.json

Format	Use case
text	Quick terminal overview (default)
dot	Graphviz rendering (dot -Tpng graph.dot -o graph.png)
mermaid	Embed in GitHub Markdown or docs
json	Programmatic analysis or custom tooling

graph stats

Displays dependency statistics for the workspace:

dart run monorepo_toolkit graph stats

Reports total package count, total edges, most-depended-on packages, and packages with the most dependencies.

graph cycles

Detects circular dependencies in the workspace:

dart run monorepo_toolkit graph cycles

Returns exit code 0 if no cycles are found, or exit code 1 with a list of detected cycles.

graph validate

Validates dependency rules from ADR-006 (architectural layering constraints):

dart run monorepo_toolkit graph validate

# Show detailed output including passing checks
dart run monorepo_toolkit graph validate --verbose

Returns exit code 0 if all rules pass, or exit code 1 with a list of violations.

Architectural rules enforced

The validate subcommand enforces these layering constraints:

Rule	Description
api-restricted-deps	*_api packages depend ONLY on shared/, utilities/, and other *_api
no-impl-cross-dep	*_impl packages cannot depend on other *_impl from different features
shared-no-upward-dep	shared/ cannot depend on features/, infrastructure/, packages/, or apps/
utility-no-upward-dep	utilities/ cannot depend on features/, infrastructure/, packages/, or apps/
no-upward-dep	packages/ cannot depend on feature impl or app packages
no-devtools-dep	App packages cannot depend on devtools packages

Dependencies must flow downward:

apps/ -> features/ -> infrastructure/ -> packages/ -> shared/ -> utilities/

Package categories

The validator automatically categorizes packages based on their path:

Category	Path pattern	Example
app	apps/	template_app
shared	shared/	feature_sdk, app_config
utility	utilities/	app_utilities, app_lints
api	*_api in infrastructure/ or features/	auth_api, monitoring_api
impl	*_impl in infrastructure/ or features/	auth_impl, monitoring_impl
feature	features/ without _api/_impl suffix	introduction
infrastructure	infrastructure/ without suffix	standalone infra packages
package	packages/	app_asset, app_ui_kit
devtools	devtools/	monorepo_toolkit

CI integration

Add graph validation to your CI pipeline to catch architectural violations early:

- name: Validate dependency graph
  run: dart run monorepo_toolkit graph validate

- name: Check for cycles
  run: dart run monorepo_toolkit graph cycles

Both commands return non-zero exit codes on failure, which will fail the CI step.

Melos shortcuts

melos run graph:visualize   # Visualize dependency graph
melos run graph:stats       # Show dependency statistics
melos run graph:cycles      # Detect circular dependencies
melos run graph:validate    # Validate architectural rules