Adoption
To adopt rules in a repository that already breaks them, record today’s violations in a
baseline, cap the untightened parts with limits, and track reach with coverage. Each is a
ratchet: it only tightens unless someone edits the manifest.
Baseline
Section titled “Baseline”A baseline is a file of violations the code already has. They stop reporting; anything new reports immediately.
baseline: .architecture-baseline.jsonarchitecture baseline # record what the repository currently violatesarchitecture check # passes, carrying those and refusing anything new- Entries ignore line numbers. Each is a fingerprint,
kind|rule|file|subject, so reformatting or moving code doesn’t break a match. - A stale entry fails
check. When you fix a violation,checkfails until you remove its entry by rerunningarchitecture baseline. So the count only goes down.
2 baseline entries no longer fire. The code was fixed; prune them: import|domain-isolation|src/modules/user/domain/user.root.ts|packages/database/src/index.tscheck reports how much you’re carrying: 1284 files, 0 violations, 37 carried by the baseline.
limits
Section titled “limits”Two manifest markers say “not this part yet”:
partial on a folder, and
unrestricted: true on an imports block (no allowlist, only prohibitions). limits caps how many
of those you have, and sets floors and ceilings on what check measures.
limits: unrestricted: 3 # at most three tiers may say `unrestricted: true` partial: 1 # at most one folder may be `partial` coverage: # floors, as fractions of the files walked imports: 0.9 structure: 0.8 members: 0.2 surface: 0.5 graph: 1 conformance: # ceilings, as counts residue: 0 vacant: 2 slack: 14 concentration: 0| Key | Checked by | Fails when |
|---|---|---|
unrestricted |
the plugin and check, at load |
more unrestricted tiers than allowed; names them |
partial |
the plugin and check, at load |
more partial folders than allowed; names them |
coverage |
check |
a family’s fraction is under its floor |
conformance |
check |
a measure’s count is over its ceiling |
Coverage floors. A file counts toward a family when:
| Family | A file counts when |
|---|---|
imports |
an import allowlist selects it (an unrestricted tier has none) |
structure |
its folder’s files are enumerated by name (an open folder doesn’t count) |
members |
a members rule selects it |
surface |
a surface rule selects it |
graph |
it is in the scope of a cycles or orphans rule |
Conformance ceilings cap the measures
architecture conformance reports:
| Measure | Counts |
|---|---|
residue |
files no family reaches |
vacant |
nodes that state an import allowlist and select no file |
slack |
allowances no import uses |
concentration |
defs entries used at fewer than half the nodes granted them |
Set each ceiling to today’s count and lower it as the count falls. Raise floors as coverage rises.
For cycles, use a cycles rule and baseline each one.
coverage
Section titled “coverage”architecture coverage prints the numbers check compares against the floors.
$ architecture coverage packages
61 files under packages
imports 61/61 100% under an import allowlist ≥ 100% ✓ structure 61/61 100% in an enumerated folder (0 in an open one, 0 in none) members 21/61 34% selected by a members rule surface 58/61 95% selected by a surface rule graph 48/61 78% in a cycles or orphans scope
unrestricted tiers: (none) partial tiers: (none)Coverage measures reach, not correctness. To test a rule, plant the violation.