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.

dependency graphTwo checks keep packages from reaching sideways or looping back

Step 1 of 6, before: Features talk to each other through *_api contract packages. home_impl depends on auth_api, never on auth_impl.

my_workspace

$ 

features/home/home_impl/pubspec.yaml

dependencies:  # …  auth_api:    path: ../../auth/auth_api  # …

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. Pass --no-fail to report cycles without failing (the --fail flag defaults to true).

graph validate

Validates dependency rules (architectural layering constraints):

dart run monorepo_toolkit graph validate

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

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

The check reads two sources for each package: the pubspec.yaml dependencies and the package: imports in lib/. With resolution: workspace, a package can import another workspace package without declaring it, and it still compiles. A violation found only through an import ends with [detected via import statement only ...].

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 another feature's *_impl or feature packages; use its *_api. A feature that is a single package (one package in its features/<name>/ directory) may be depended on
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