encapsulation

Code outside a unit may only import it through its entry points, while code inside it may import anything in it: the "public API" rule, with no deep imports into a package or a feature's folder. import-linter has no equivalent.

Example

[contracts.ui-public-surface]
type = "encapsulation"
modules = ["pkg:@acme/ui"]
entrypoints = ["index", "src/components/*/index"]
severity = "warn"
index.ts src/components/button/index.ts src/components/button/Button.tsx entry point entry point internal web/src/app/page.tsx @acme/ui packages/ui a deep import
Outside @acme/ui, code may import its entry points. Importing Button.tsx directly is a deep import.

Outside @acme/ui, code may only import the package's index and the index of each component's directory. web importing @acme/ui/src/components/button/Button.tsx is a deep import, reported as a warning while the existing ones are migrated.

Options

OptionDefault
modulesrequiredSelectors of directory units.
entrypoints["index"]Globs relative to each unit's root, with or without an extension. They match files only: public/** exposes a directory.
allowed_importers[]Selectors of importers that may import anything, such as tests.

Common options

Like every contract type, encapsulation also takes:

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.