Skip to content

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.

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.

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: findOneByEmail

Write 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: makeCommandBus

imports rules have no authored probe.

  • 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.