Skip to content

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.

A baseline is a file of violations the code already has. They stop reporting; anything new reports immediately.

baseline: .architecture-baseline.json
Terminal window
architecture baseline # record what the repository currently violates
architecture 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, check fails until you remove its entry by rerunning architecture 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.ts

check reports how much you’re carrying: 1284 files, 0 violations, 37 carried by the baseline.

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.

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.