Probes
A rule that stops matching anything keeps passing forever, and looks exactly like a rule that works. To catch that, every compiled rule carries a probe: a synthetic case, generated from the rule’s own pattern, that the rule must reject. If any rule passes its probe, the policy refuses to load and the lint run fails.
| Family | The probe |
|---|---|
imports |
a file the rule’s from selects, importing a target it must refuse |
exports |
an importer outside except, naming a restricted symbol |
members |
a selected file declaring or calling a name the rule must reject |
surface |
a selected file exporting a site the rule must reject, or (for count) a surface of the wrong size |
structure |
a filename the layout must reject; for parity, a sibling it must demand |
graph |
a small graph the rule must report: two files importing each other, a lone file, an edge outside via |
A rule that admits everything by design, such as the layout of a
layout: open folder, has no probe.
What a probe can’t check
Section titled “What a probe can’t check”A generated probe proves a rule can fire, not that it fires on the code you meant. It never
meets a parser: a members rule about a declaration shape the parser doesn’t read passes its probe
and enforces nothing. For that, write the probe yourself.
Writing the probe yourself
Section titled “Writing the probe yourself”A members, exports or surface rule may carry probe: { source, … }. At load, the snippet is
parsed like real code and the rule must report the named site. If it doesn’t, the rule is refused.
"*.repository.ts": members: - message: 'Port method "{name}" is not in the vocabulary.' subject: members declares: [type, interface] in: "*RepositoryShape" allow: [findOneById, save] probe: source: "export type TodosRepositoryShape = { findOneByEmail(): void };" name: findOneByEmailWrite the snippet in the shape your real code takes. Members are read from type aliases and
interfaces, through intersections and unions, but not from a class body, so a rule probed with a
class refuses to load. Run architecture facts
to see what the parser reads.
For exports, the snippet is an import and symbol is the binding. Every edge in the snippet is
taken to reach module. Use symbol: "default" for a default import and "*" for a namespace one.
exports: - name: bus-factories message: "Only a composition root may build a bus." module: "**/node_modules/@org/cqrs/**" symbols: [makeCommandBus] probe: source: 'import { makeCommandBus } from "@org/cqrs";' symbol: makeCommandBusimports rules have no authored probe.
Two more habits
Section titled “Two more habits”- Plant the violation. Before trusting a new rule, create the file it exists to catch and watch the check fail.
- Keep an edge table. Check a list of
(importer, specifier, expected verdict)rows on every run. Include allowed rows: only those catch a rule that got too strict.
Two other ways a policy silently stops enforcing are handled elsewhere: an unresolved import is an error, and a stale plugin build enforces a stale policy, so build before you lint.