Skip to main content
← CLI Reference

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."
}
]
}
FieldMeaning
componentsComponent paths this rule applies to (one per package where the repo has them, else the containing directory)
mayDependOnAllow-list of components this may depend on. Any dependency outside it is a violation. [] means no internal dependencies at all
mayBeUsedByAllow-list of components allowed to depend on this one. Anything else that does is a violation
acyclicWhen true, the whole graph is checked for dependency cycles regardless of components
becauseRequired 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​

CodeMeaning
0No rules declared, or every declared rule holds
1At 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 guard for the other CI-facing gate, enforced at tool-call time inside an agent session rather than as a graph-wide check