Skip to content

Conformance

check tells you whether the tree passes. conformance tells you how far it is from the policy: files no rule reaches, rules no file reaches, violations, and allowances nothing uses. It is a measurement and never fails. To fail a build on a measure, set a ceiling in limits.conformance and check enforces it.

Terminal window
architecture conformance [roots…] # text report
architecture conformance --json [roots…] # snapshot document
architecture conformance --against target.yaml [roots…] # measure against another manifest
Part What it is
Residue Files no family reaches (no allowlist, open folder, no members/surface rule, no graph scope), and folders made only of them.
Vacancy Nodes that state an import allowlist but select no file.
Violations What check reports, baselined or not, cheapest to fix first (edges to leaf modules before edges to widely imported ones).
Slack Entries in imports.allow or imports.external that no import uses.
Concentration Entries from a defs fragment used at some of the nodes granted them but not others.

Vacant nodes are either a tier declared before its first file, or a pattern that no longer matches. The report can’t tell which, so it names the node and leaves the call to you:

vacant: 2 nodes select no file
components/primitives/**/*.test.ts 14 allowances
modules/{module}/event-handlers 10 allowances

A node isn’t vacant while an overriding child has files, and a children entry with no files and no allowlist isn’t vacant either.

Slack is what separates a strict manifest from a permissive one. It also flags an allowlist widened just to make a build pass. Each entry names the node that wrote it. An entry that came through use is reported once, against the defs fragment, and only when no node granted it uses it. An entry used at only some of those nodes is concentration, not slack. The text report lists entries used at fewer than half:

slack: 3 allowances nothing imports through
modules/{module}/commands: allow "packages/server/src/platform/notifications/**"
contracts: external "@effect/vitest"
test-file: external "stripe" (via use, at 24 nodes)
concentrated: 1 allowance used at fewer than half the nodes granted
test-file: external "@effect/sql-pg" used at 1 of 24 nodes

A vacant node’s entries count as neither slack nor concentration. Only imports.allow and imports.external are measured; unused importedBy entries are not reported.

--against <manifest> measures the tree against a different manifest, such as the architecture you’re moving toward. The report shows the violations between here and there and the allowances the target grants that nothing would use. The snapshot’s manifest.path names that file. Only conformance takes this flag.

--json prints one document to stdout, defined by /schema/conformance.schema.json. It extends check --json: version, manifest, roots, files, ok, coverage, conformance, violations, unresolved, stale and adoption mean the same there. ok is what check would exit with.

{
"version": 1,
"manifest": { "path": "architecture.yaml", "sha256": "…" },
"roots": ["packages"],
"files": 94,
"ok": true,
"coverage": { "imports": { "covered": 94, "total": 94, "floor": 1 } },
"conformance": {
"residue": { "count": 0, "ceiling": 0 },
"vacant": { "count": 0, "ceiling": 0 },
"slack": { "count": 2, "ceiling": 5 },
"concentration": { "count": 0, "ceiling": 0 }
},
"residue": { "files": [], "folders": [] },
"vacant": [],
"violations": [],
"unresolved": [],
"stale": [],
"baseline": { "size": 0 },
"cycles": 0,
"slack": [{ "node": "typescript", "kind": "allow", "entry": "packages/core/src/testing.ts" }],
"concentration": [],
"adoption": { "unrestricted": [], "partial": [] },
"campaigns": []
}
Field Contents
conformance The four measures as counts, each with its ceiling when limits.conformance sets one.
residue Unreached files, sorted, and the topmost folders made only of them.
vacant Vacant nodes with how many entries each wrote, in manifest order.
violations Every finding, baselined included, cheapest first.
baseline.size Entries in the baseline file.
cycles Every cycle in the walked graph, in a cycles rule’s scope or not.
slack Unused allowances in manifest order. An entry from use carries fragment and of, and its node is the fragment name.
concentration Partly used fragment entries, with usedAt and of.
campaigns Each campaign: objectives (ledger totals: initial, allowed, count, cleared, closed, progress, lastCleared, concessions, phase), phases, sectors (phase, reached, files, residue per objective), legacy, plan (refined, changed, unreceipted), stalled, complete. See The ledger.

To compare snapshots across commits: manifest.sha256 tells you whether the policy changed, and violations are keyed by line-independent fingerprints. decodeSnapshot in @goodbones/core reads a snapshot back and refuses unknown keys.