Contracts

Contracts are tables under [contracts.<id>]. The id is how --contract, the baseline and suppression comments refer to the contract: it may contain ASCII letters, digits, - and _, and is kebab-case by convention.

from to … forbidden from must not reach to a b c independence units must not depend on each other a b c layers imports point down, never up high mid low agents allowed other protected only some may import it directly a b c acyclic units must not form cycles index inner user encapsulation only through its entry points m a b c x limits only so many importers and imports allowed violation warning unit import
The seven contract types. Each diagram leads to its page.
TypeRule
forbiddenSome units must not import others, directly or through any chain of imports.
independenceUnits must not depend on one another.
layersHigher layers may import lower layers, never the reverse.
protectedOnly some importers may import a unit directly.
acyclicUnits must not depend on each other in cycles.
encapsulationA unit may only be imported through its entry points.
limitsA unit may only be imported by so many files, and import so many modules.

Common options

Every contract type takes these options:

OptionDefault
typerequiredThe contract type, such as "layers".
namethe idThe title shown in the output.
severity"error""warn" reports a broken contract without failing the check, for rolling a contract out gradually.
exclude_kinds[analysis] exclude_kindsThe import kinds to leave out, e.g. ["type"].
reexports[analysis] reexports"transparent" sees an import of names from a [pass-through module](../concepts.md#pass-through modules) as imports of the modules that define them, as bundlers load them; "opaque" as an import of the pass-through module. Not for encapsulation.
ignore_imports[]"<selector> -> <selector>" entries: the direct imports between them are left out of the contract.
unmatched_ignore_imports"error"Whether an ignore_imports entry that matches no import breaks the contract ("error"), is a warning ("warn") or is fine ("none").
guidancenoneText shown under each violation, such as how to fix it.

An import between two files is left out of a contract when none of its statements count: each statement may be of an excluded kind, suppressed with a comment, ignored, or in the baseline.