Regression in 7.4.0: `--order-dependents` now fails on graphs with `dev_dependency` cycles that were previously tolerated

[dennishenle]

Upgrading from melos 7.3.0 to 7.4.x / 7.5.x causes melos exec --order-dependents (and any script that sets orderDependents: true, including the common build_runner recipe) to hard-fail with

🚨 1 cycles in dependencies found:
[ A -> B -> C ]

Environment

• melos --version: 7.4.1 (also reproduces with 7.4.0 and 7.5.1)
• Dart SDK: 3.10+
• OS: macOS 15 (also reported internally on Linux CI)
• Workspace: Pub workspace (Melos 7.x), root pubspec.yaml

Minimal reproduction

The scenario below mirrors a very common Dart/Flutter monorepo layout: a shared
test_helpers package that imports the real types from every feature package
so it can expose mocks and pump helpers, and each feature package pulling
test_helpers back in via dev_dependencies to use those helpers in its own
widget/unit tests.

Three packages in a workspace:

# packages/test_helpers/pubspec.yaml
name: test_helpers
resolution: workspace
dependencies:
  ui: 0.1.0       # needs the real types to mock
  auth: 0.1.0

# packages/ui/pubspec.yaml
name: ui
resolution: workspace
dev_dependencies:
  test_helpers: 0.1.0   # uses the shared mocks/pump helpers in widget tests

# packages/auth/pubspec.yaml
name: auth
resolution: workspace
dependencies:
  ui: 0.1.0
dev_dependencies:
  test_helpers: 0.1.0   # same pattern, closes a second cycle

The test_helpers ↔ ui and test_helpers ↔ auth edge pairs each form a cycle
through dev_dependencies. In a real monorepo this pattern repeats for every
feature package (banking, contacts, …), so the graph ends up with many
such cycles.

Running:

melos exec --order-dependents -- echo hello

Observed behaviour

• On 7.3.0: command runs successfully in every package.
• On 7.4.0+: fails immediately with

🚨 1 cycles in dependencies found:
[ test_helpers -> ui -> auth ]

Expected behaviour

Treat cycles involving only dev_dependencies as non-fatal (or just ignore dev_dependencies when computing execution order), since dev_dependencies aren't transitive in pub and therefore don't actually impose an ordering constraint on code generation or test execution across packages.

Request

Document the change as BREAKING in the 7.4.0 changelog and recommend pinning to 7.3.0 until the graph is a DAG.

Workaround

Pinning melos: 7.3.0 in the root pubspec.yaml restores the previous behaviour. This is what we've done for now.

[spydon]

This is probably an effect of #976 or #977, right @sikrinick ?

Document the change as BREAKING in the 7.4.0 changelog and recommend pinning to 7.3.0 until the graph is a DAG.

I don't think this part of the PR was an intentional breaking change, even though those PRs were breaking (but accidentally didn't get their scope tagged as such in the conventional commit tag, only in the PR description).

Treat cycles involving only dev_dependencies as non-fatal (or just ignore dev_dependencies when computing execution order), since dev_dependencies aren't transitive in pub and therefore don't actually impose an ordering constraint on code generation or test execution across packages.

Sounds like a sensible behavior.

[sikrinick]

@spydon Yes.

However, I am not sure how it can elegantly solved.
Previous implementation of sortPackagesForExecution, that relied on topologically sorted list, ran echo hello for [ui, auth, test_helpers] in parallel.
New implementation makes an order and then runs.
In the example provided order does not matter, as it doesn't matter when exec hello will run for test_helpers.

If we assume, that devDependencies should be ignored, then fixing this seems trivial:

But this conflicts with exec command contract, as it is expected to be run for each package in a workspace.

To be honest, I don't know how to order devDependencies in this case, if we may allow devDependencies to be cyclic dependencies with dependencies

Therefore, @dennishenle, can you, please, elaborate, why orderDependents: true is required in this case?

[dennishenle]

The issue we had was especially with our build_runner command:

    # root pubspec.yaml
    melos:
        scripts:
            build_runner:
                name: Generate files
                run: dart run build_runner build --delete-conflicting-outputs
                exec:
                    concurrency: 6
                    orderDependents: true
                packageFilters:
                    dependsOn: build_runner

We built our app as a layered architecture core, data, services, models as base and repositories and ui logic on top. So the repositories and the ui are dependent on the base packages. We wanted to make sure that everything is build correctly what was dependent from another when we build everything at once. We didn't think about the dev dependency (our test helper package) there because it was tolerated until 7.3.0.

[sikrinick]

I introduced this change intentionally via #976/#977 to fix build ordering in large monorepos.
In our case, we needed it run build_runner in 200+ modules with a strict layered topological order.

The old behavior wasn't tolerant of dev_dependency cycles — it was silently incorrect. It would pick an arbitrary execution order, which means if your build_runner/dart_mappable/freezed generated code depends on types from a cyclically-linked package, the generated output could be wrong with no error surfaced.

Let's say test_helpers will have build_runner as dependency.
Then it generates code based on types from ui, and ui dev-depends on test_helpers for its own code generation — that cycle is genuinely unresolvable. No execution order can make both correct in a single pass.

The only fix I see is to break the cyclic dependency by breaking test_helpers into two packages: one with shared interfaces/types (which ui can depend on normally), and one with mocks/pump helpers (which depends on ui).

[dennishenle]

That would be the best solution. In our app, test helper package doesn't have build runner as dependency. So technically we wouldn't need it in the build runner step at all. Melos doesn't know that of course. It only sees the dependencies circling. Is there a possibility to exclude the test helpers package from the build runner script completely so that this dependency circle can be ignored?

[sikrinick]

As far as I know – currently there is no way.
During exec phase there are 2 lists — executable packages (the list of all packages processed with filtering options), and all packages (based on which layered topological sort is done and List<List<Package>> is built).

All filtering options are applied to produce executable packages, so currently there is no way to filter from that internal allPackages package list.

I can add a PR next week, that adds an option to filter packages during layering phase by name.

But I will need support from @spydon, at least with naming of this flag.

[spydon]

But I will need support from @spydon, at least with naming of this flag.

Ouff, naming is always hard... The topological sort is only active when doing --order-dependents right? What about --order-dependents-ignore or something like that, to mirror the normal --ignore flag?

Hmm, or what would happen if we just removed the packages in allPackages that are passed in to the normal --ignore flag too? That would feel cleaner, but it would of course also change the behavior a bit.

[sikrinick]

Hmm, or what would happen if we just removed the packages in allPackages that are passed in to the normal --ignore flag too? That would feel cleaner, but it would of course also change the behavior a bit.

Unfortunately, that's not an option.
Let's say we have a => b => c.
In this case c is transitive dependency for a.
If we pass b with ignore flag, we will build correct layers: [[c], [b], [a]] and only [[c], [a]] will be executed.

If we ignore b not only during execution, but also during layering — instead of having [[c], [b], [a]] we will have [[c, a]], where [c, a] means parallel execution, as we have no information to relate c to a.

In a project I am currently working on I am relying on diff filter to make a run of build_runner only in changed packages.
In this case developer can change code in 2-3 out of 200, but build_runner will run only in those 2-3 changed modules, but in order based on project structure, not based on relationship between those modules.
It was implemented in those PRs related to orderDependents logic change.

(It is still incorrect, as it omits modules that have to be regenerated because there dependent changed, but that's a trade-off)

[sikrinick]

Based on code of workspace.dart, there is, probably, a way to solve by using ignore and scope, as it applies to list of allPackages.

@dennishenle, can you, please, try to ignore "test_helpers"?

For example,

melos exec --order-dependents --ignore="test_helpers" -- echo hello

If it works, then in your project you may need next script to run build_runner a bit sequentially.
You may run it in test_helpers at first, and then in all other packages.
Something like this:

melos:
  scripts:
    build_runner:
      steps:
        - melos run build_runner_test_helpers
        - melos run build_runner_all
    
    build_runner_test_helpers:
      packageFilters:
        scope: "test_helpers" # To run only in "test_helpers" package
      run: dart run build_runner build -d

    build_runner_all:
      exec:
        orderDependents: true
      packageFilters:
        ignore: "test_helpers" # To skip "test_helpers" package as it should be run separately
      run: dart run build_runner build -d

[spydon]

@dennishenle just pinging here to see if you've tested @sikrinick's suggestion