Skip to content

C0011 module-graph-scc

Rule: No module cycle holds most of a crate's code.

Code C0011 (stable, never reused)
Id module-graph-scc
Category structure
Source spirit_level
Fix by hand

Level per tier

Tier Level Reason
small off
small-workspace off
medium warn a module cycle holding most of a crate can't be split into crates; cut it while it is small
big warn a module cycle holding most of a crate can't be split into crates; cut it while it is small
ai off
embedded off
ui off
egui off
units-strict off
units-paranoid off

Parameters

Name Type Default Meaning
max-share number 0.5 share of a crate's code lines its biggest module cycle may hold
min-lines integer 3000 crates with fewer code lines are not checked
depth integer 1 module depth of the graph's nodes: 1 groups every module under its top-level module
max-listed integer 12 modules and cut edges the message names

Why

A crate grows by adding modules, and modules start to reach into each other: core calls a helper in records, records calls back into core. Each reference is harmless alone. Together they form a cycle, a strongly connected component of the module graph, and every module in it depends on every other. Such a component can't be split into crates, can't be tested apart, and every change inside it can break any part of it.

tpm_cli is the example: one component held 148 of its 188 top-level modules and 85% of its 330,000 lines. Splitting it into crates first needed 288 upward references over 125 module pairs cut. This lint reports such a tangle while it is still small enough to cut.

What is measured

  • The graph's nodes are the crate's modules, grouped under their top-level module (parameter depth). The crate root's own code is the node (root).
  • An edge counts the references from one node into another: every crate::, super:: and self:: path, every path that starts with a child module's name, every use leaf, and every use of a name a use brought in. Paths inside macro calls count. Re-exports are followed to where the item is defined, so a pub use at the root does not make a false cycle.
  • The share is the code lines of the biggest component (by code lines) over the crate's code lines. Test code is left out.

The finding names the modules of the component, biggest first, and the references to cut so that no cycle is left, fewest first, each with the place of its first reference. The cut comes from ordering the modules so that as few references as possible point back up (Eades-Lin-Smyth with adjacent swaps): a good cut, not a proven minimum.

Crates under min-lines code lines are not checked: a small crate with a cycle between three modules does not need splitting.

Example

warn[module-graph-scc] tpm: one module cycle holds 85% of its code lines (280412 of 330091), 148 modules:
  core, sync, ui, ...; cutting 288 references over 125 module pairs breaks it, the fewest first:
  keep_trial -> keep_trial_cmd (1), ...

How to fix

For each listed reference, pick one:

  • Move the item it uses down, into the referenced module's side or a module both can use.
  • Turn the call around: the lower module takes a function, a trait object or a table of functions that the upper one installs.
  • Merge the two modules when they are really one subject.

Cut the cheap ones first. When the cycle falls apart, the parts can become crates, and the crate map's layers keep them apart from then on.

Configure

[lints.module-graph-scc]
level = "deny"
max-share = 0.5
min-lines = 3000
depth = 1
max-listed = 12
reason = "why this project wants it at this level"

Allow one finding in the code with // spirit-level: allow(module-graph-scc) <reason> (waivers); the code works there too, as in [lints.C0011].