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.
architecture conformance [roots…] # text reportarchitecture conformance --json [roots…] # snapshot documentarchitecture conformance --against target.yaml [roots…] # measure against another manifestWhat it measures
Section titled “What it measures”| 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 allowancesA 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 nodesA 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
Section titled “--against”--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.
The snapshot
Section titled “The snapshot”--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.