travsr invariants
Check declared architecture rules against the graph, and exit non-zero on a
violation, so it works as a CI gate. The rules live in
architecture-invariants.json at the repository root, in the repository,
reviewed like code, rather than restated in prose (a CLAUDE.md, a wiki page)
that drifts from what the graph actually shows.
travsr invariants
If the repository has no architecture-invariants.json, it prints a note and
exits 0: nothing declared is not a failure.
Writing rules
{
"invariants": [
{
"name": "parsing stays pure",
"components": ["crates/travsr-analysis"],
"mayDependOn": ["crates/travsr-core"],
"because": "travsr-analysis depends on travsr-core and nothing else, so parsing can never reach storage, retrieval or the plugin host."
},
{
"name": "one trust boundary",
"components": ["crates/travsr-plugin-protocol"],
"mayBeUsedBy": ["crates/travsr-plugin-host", "crates/travsr-plugin-sdk"],
"because": "Only the plugin host is allowed to depend on the wire format, which keeps the trust boundary in exactly one crate."
},
{
"name": "no dependency cycles",
"acyclic": true,
"because": "No circular dependencies, ever."
}
]
}
| Field | Meaning |
|---|---|
components | Component paths this rule applies to (one per package where the repo has them, else the containing directory) |
mayDependOn | Allow-list of components this may depend on. Any dependency outside it is a violation. [] means no internal dependencies at all |
mayBeUsedBy | Allow-list of components allowed to depend on this one. Anything else that does is a violation |
acyclic | When true, the whole graph is checked for dependency cycles regardless of components |
because | Required rationale, printed alongside a violation so the report explains itself rather than just failing |
A rule naming a component the graph no longer has is reported as VIOLATED, not skipped: renaming or removing a crate cannot silently disable the rule that protected it.
--provenance
travsr invariants --provenance ratified # default: confirmed edges only
travsr invariants --provenance "" # accept everything, including the live overlay
travsr invariants --provenance scip # only edges from one provenance
Accepted values are ratified (the default), "" (all edges), or exactly one
provenance: tree-sitter, lsif, scip or live.
An unrecognised filter is rejected outright, with exit code 1 like a violation, rather than silently matching zero edges, which would report every rule as holding over an empty graph.
Exit codes
| Code | Meaning |
|---|---|
0 | No rules declared, or every declared rule holds |
1 | At least one rule is violated, or the --provenance filter is not recognised |
When to run it
- As a CI step on every pull request, so an architecture rule breaks the build the same commit it is broken, not whenever someone next reads the CLAUDE.md.
- After a refactor that moves code between components, to confirm the dependency direction you intended is the one the graph now shows.
See also
travsr guardfor the other CI-facing gate, enforced at tool-call time inside an agent session rather than as a graph-wide check