Module rules 

The rule surface shared by ct-rules (say what the rules are) and ct-check (verify them): the .ct/rules.jsonc store model, upward discovery, def expansion, the probe gate, the external-tool bridge, and the expect outcome adapters.

A rule is one recorded, framed observation: an id, the question it answers, the probe (an argv vector, never a shell) that answers it by scanning for known violations, and the why behind it. Defs are the store’s named vocabulary, expanded as {def:NAME} inside probe argvs. Probes are gated to the suite’s fixed read-only set plus the compiled-in BRIDGE of known read-only invocations of established Rust tools — a store entry selects from the gate and can never extend it.

The full specification is docs/specs/rules.md.

Structs

BridgeEntry

One compiled-in external invocation rules may leverage. The table is immutable: a store entry selects from it and can never extend it.

Rule

One recorded rule.

Store

The parsed store.

Enums

Adapter

How a probe’s outcome is read as a verdict. Observers speak the suite’s exit contract (Exit); bridge tools need an adapter.

Def

A def: the store’s named vocabulary. Untyped — a string expands in place; a list expands to multiple argv elements.

Gated

What the gate resolved a probe to.

ProbeOutcome

A probe’s classified outcome (before lane mapping).

Severity

Rule severity: whether a violation reddens the exit status.

Constants

BRIDGE

The compiled-in bridge: known read-only invocations of established Rust tools. See docs/specs/rules.md §5.

STORE_FILE

The store’s path relative to the .ct directory.

Functions

bridge_argv

The argv actually launched for a bridge probe: the rule’s argv plus the entry’s enforced flags and hermetic flag (skipping flags already present). network drops the hermetic flag only where the entry deems it meaningful.

classify

Classify a finished probe through its adapter. code is the exit code (None for a signal death — broken). Returns the outcome and a one-line reason. Timeouts are handled by the caller (always broken).

discover_root

Walk upward from start to the nearest directory containing .ct, git-style. Returns that project root, or None when no .ct exists up to the filesystem root.

expand_defs

Expand {def:NAME} tokens in a probe argv. An element that is exactly one {def:NAME} token whose def is a list splices to multiple elements; a string def expands inside elements. A list def referenced inside a larger element, or an unknown def, is an error (the rule is broken).

gate_probe

Gate a (def-expanded) probe argv. Returns how it may run, or a refusal naming the reason. The gate is fail-closed and compiled in.

parse_store

Parse and validate the JSONC store text.

probe_root

The directory probes run from: store paths are root-relative, so a probe’s working directory is the project root (the parent of the .ct directory holding the store), regardless of where the tool was invoked. For a --file outside a .ct directory, the file’s own directory.

run_probe

Run one gated, def-expanded probe to completion and classify it. The probe runs from root — store paths are root-relative, so rules behave identically wherever the tool was invoked. Launch failures (e.g. a bridge binary not installed) and timeouts are broken, never errors: a defective probe is a maintenance signal the caller reports, not a crash.

store_path

The store path under a project root.