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::andself::path, every path that starts with a child module's name, everyuseleaf, and every use of a name ausebrought in. Paths inside macro calls count. Re-exports are followed to where the item is defined, so apub useat 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].