lib-layers
Rule under the lib-imports law. Load when editing project manifests, build paths, linter boundaries, any barrel and the layout checks, and when deciding where a shared symbol lives. Patterns lib-layer
SKILL.md.claude/skills/lib-layers/SKILL.md
GitHub<!-- rt-kit v0.35.0 · rules/lib-layers.md · 1e28c6604abb · правится надстройкой, не здесь -->
Imports between libs — how it works here
Rule under the law docs/constitution/lib-imports.md. The law says who sees whom; here — how it is
cut in this tree, what it is called and what we do not have.
What it is called here
| In the law | Here |
|---|---|
| lib family | the frontend families listed by the families key of the checks' settings, and the backend family named by the apiFamily key |
| layer | api, data-access, feature, shell, ui, util |
| the right to see a lib | a tag in eslint/boundaries/domains/<family>.config.mjs |
| lib shared by every application | libs/common/util, tag scope:common-util |
| family base | <family>/core; its tag is in ADMIN_UNIVERSAL |
| barrel | src/index.ts of the lib and index.ts of the component directory |
A feature domain of the frontend has six layers (api, data-access, feature/<screen>, shell,
ui, util), a common domain the same without shell. The backend has no ui and no shell: it
has nothing to serve markup with or to route by.
Where it lives
In this tree — the table in implementation.md next to it. Paths live there, not here: the rule
travels between repositories, the layout does not, and a path named in the rule lies in the first
tree that keeps its code differently.
Flow
The flow of declaring a shared symbol: where it must live, what to do with a missing import right and how the boundary is checked.
flowchart TD
A[A shared symbol is needed] --> B{It is about the subject or the mechanics}
B -->|Subject| C[Lives in the domain of that subject]
B -->|Mechanics shared by several domains| D[Lives in the family base, not in a new domain]
C --> E{The import is allowed by the boundaries}
D --> E
E -->|Yes| F[Imported by the lib alias]
E -->|No| G{The right is legitimate}
G -->|Yes| H[Added as a line in the boundaries config, with a reason]
G -->|No| I[The symbol moves where both sides can see it]
H --> F
I --> F
F --> J{The symbol is foreign}
J -->|Yes| K[Not re-exported outward in any form: the barrel gives only its own]
J -->|No| L[The barrel gives it by alias, not by relative path]
K --> M[The boundary is checked by an introduced violation, not by a green run]
L --> M
How the law applies here
- A foreign symbol is not re-exported in either of the two forms. Both
export { X } from '@<scope>/…'and the pair "import plusexport { X };" are forbidden. The second looks like an own declaration and passed review by eye. - A line with a foreign lib alias in a barrel is the same re-export. A relative path in a barrel is legitimate: it collects the lib's own files outward.
- A missing right is added as a line in the domain config with a comment. An import that "just worked" means the tag is not narrowed yet.
libs/common/utilhas an empty dependency list, and Angular does not get in. The backend imports the lib, and the framework would ride into its bundle; a DI token shared by the two frontend families lives incommon/platform.- The family base sees only
util. Every domain of the family calls it, and any dependency of it becomes shared by all at once. - Behaviour the family base cannot see comes to it by a token. The token is declared in the
utilof the common domain, anddata-accessputs its implementation there: so the base calls it without seeing its lib. Widening the base boundaries for one call opens that lib to every domain of the family at once and never narrows back. - A domain is started for a subject, not for mechanics. Mechanics shared by several domains ride
into the lib that already sees them. On the frontend that is the family base, on the backend the
utillayer listed with every domain. - The name of a lib is what its manifest declares, and the path only suggests it. The tag and the import alias are derived from that name, and the audit reads all three from the manifest and the list of paths instead of assembling them from the directory. Where the manifest declares no name, the path says what the name must become.
- A domain with exactly one non-empty layer is listed as a line with a reason. Otherwise it cannot be told from a slot: both have empty layers, and a barrel lies in both.
What of the law is not here
Today the family base deviates from the ladder once, and it is named in CORE_EXCEPTIONS of the
check: common/proto and common/connect for admin/core, for the sake of Connect transport.
The full set of layers is required of everyone, and an empty layer is not a defect: api is empty
in a domain that talks to no one foreign. Only the edge case is judged — exactly one non-empty
layer; such a domain is usually one, and it stands in the exceptions list with a reason.
Patterns
lib-layers-new— create or remove a lib: generator, tags, alias, README.lib-layers-move— move code between libs: order, boundaries, imports, README of both.
Pitfalls
- A lib nobody imports is checked by nothing.
nx lintandnx testcheck the lib itself, not its contract with the consumer: a lost field in*.Stateis not an error while there is no calling code. The first importer is the first check — the models layer is accepted afternx buildand a live run of the scenario, not by a greenlint test. - A configuration a target does not declare is a default, not a refusal. The builder drops an unknown name silently: the exit code is zero, the artefact is built by the default, and only the line of the build output, where the target is named without a configuration, tells this from a real build. Hence the reading rule: what is built with is said by the build output, not by the list of configurations in the target manifest — that one says what may be called, not what is called. A rollout pipeline called a server build with a production setting the target did not have, and for half a year the line promised what it did not do.
- A check is accepted on a violation, not on a green run. The violation is introduced by hand,
the run turns red, the edit is reverted. The checks in
tools/have no tests, and this is the only acceptance. git rm -rleavesnode_modules/.viteinside the removed directory, and the check keeps seeing it as a domain without layers. Finish withrm -rf.- A snippet written a second time is caught by
npm run check:dupes— ruleshared-code.
Import cycles inside the package
The check is npm run check:cycles. It reads the relative imports of every file under
projects/ and names each cycle by its members, from file to file.
- A cycle starts through a directory barrel. A file takes its neighbour not directly but from
the
index.tsnext to it, and that one collects the file itself as well. It is broken by a direct file import:from './index'becomesfrom './table-column.interface'. - Neither the build nor the linter judges a cycle. The bundler breaks it itself and hands one of the members a half-assembled module; it surfaces at the consumer — a symbol read at startup turns out empty.
- Mutual recursion of two functions is not cured by a barrel. Two deep-comparison functions call each other in essence, and apart they are a cycle in any case: both live in one module, and the former addresses of the symbols stay thin re-exports.
- A component taken as a parent through
injectis replaced by a token. A side-menu subitem injected the menu component itself, and the menu declared the subitem among its imports; a token in the types file separates the two. - Types both sides need move to a file of their own. The kit config named the button appearance by types from its component file — a cycle of types alone survives the build, but it lives only until the first edit that adds a value to it.
- The check stands in the push gate set and in the pipeline. A cycle removed once comes back with the first edit nearby, and there is nothing to notice it with.