Skip to main content

Crate termproof

Crate termproof 

Source
Expand description

TermProof: evidence-first verification for TUI and terminal applications.

§Layout

This crate was merged from three (termproof-core, termproof-terminal, termproof-evidence) before any of them was published, so the shape below is the only one that has ever existed on crates.io.

  • The crate root is what was termproof-core: the recipe model, config, schema, validation, the built-in steps and assertions, planner/runner/execution, store/cache, and the py* compatibility shims that keep this port close to the Python oracle. It is flat rather than under a core module, both because it is the crate’s primary surface and because a module named core shadows the core crate for every path in its scope.
  • terminal is what was termproof-terminal: PTY, tmux and process sessions, plain and attributed screen state, asciicast recording, idle detection and the terminal::SessionBackend implementations.
  • evidence is what was termproof-evidence: screenshot and video rendering, Markdown reports, visual baselines, diff and upload.
  • junit is the JUnit XML writer. It was in termproof-evidence too, and evidence::report still re-exports it, but it reads a RunResult and renders nothing, so #34 moved it out to where it can be compiled without the renderers.

The two nested modules keep their own re-exports rather than flattening into the root. error is defined by both the root and terminal, so nesting is what keeps crate::error and terminal::error apart; the same nesting keeps crate::result clear of evidence::report, and keeps the reader’s sense of which layer a name comes from.

Original module notes: models, config, schema, registries, planning, orchestration and execution (RUST-004 + RUST-010 + RUST-016); PTY/process ownership, terminal screen, cast recording, idle and session backends (RUST-005/006 + RUST-012 + RUST-016); and the evidence pipeline.

§Features

The first four are on by default, so a consumer that does not name features gets the crate as it has always been published. clap is the exception: it is off by default, so --all-features and default are no longer the same set.

  • evidence — the evidence module. Off, the crate does not compile image or avt.
  • junit — the junit module and the generate_junit re-exports in evidence. Off, the crate does not compile quick-junit. It does not imply evidence and is not implied by it: JUnit is written from a RunResult, so the two are independent in both directions (#34).
  • json-schema — validation, pyschema and the json_schema built-in assertion. Off, the crate does not compile jsonschema, and json_schema is absent from assertions::BUILTIN_TYPES rather than present and failing. Implies schema, which is where the schema it validates against comes from.
  • schema — the schema module and the JsonSchema impls derived on Recipe, config::VerifierConfig and the types they contain. Off, the crate does not compile schemars. It is the only dependency left in the public API (below), and the only one that could not be wrapped out of it, because the derives put JsonSchema on the published types themselves rather than in a signature; turning it off is how a consumer on a different schemars major stops carrying two.
  • clap (off) — run_config’s cli submodule: a clap::Command carrying the standard flags for a run_config::RunConfig, and the parse back into one with run_config::pick applied once rather than per flag. Off, the crate does not compile clap. It is the only default-off feature of the published API, and for the mirror image of the other four’s reason: they subtract from a shape that was already published, so default-on is what keeps turning one off from being a break; this adds a shape that never was, so default-off is what keeps it from being a change (#197).
  • _test-harness (off) — not part of the published API. It exists for this repository’s own conformance tests, adds no module and no dependency, and carries no stability guarantee; do not enable it.

terminal has no feature of its own: the crate root is built on it, and every build drives a terminal, so there is nothing to save.

§Dependencies in the public API

A third-party type in a public signature makes that dependency’s version requirement a source-compatibility surface, and not just a question of how many copies the graph carries: two copies of a crate are two unrelated types, so a consumer that names one compiles only when its copy is the copy cargo handed us. Cargo resolves a requirement to the top of its range, so the window of versions a consumer can unify with is one version wide however the range is written — widening it moves the window rather than enlarging it (#177).

A signature is not the only door. A re-exported crate is public API too — termproof::dep::Type names the same type as dep::Type and carries the same requirement — and so is anything a public trait impl renders, since a derived Debug over a private field publishes that field’s formatting. 0.4.0 closed all three:

DoorWasNow
return typepyregex::compile gave a fancy_regex::Regexpyregex::PyRegex, with pyregex::PyCaptures and pyregex::PyMatch so reading a match does not re-leak
return typepyschema::compile gave a jsonschema::Validatorpyschema::PySchema
argumentterminal::attributed::from_vt100 took a vt100::Screencrate-internal. Nothing public accepts a caller-built vt100 value; terminal::screen::TerminalScreen takes bytes and owns its own parser
re-exportpub use fancy_regex, jsonschema, vt100removed
trait implPyRegex’s derived Debug rendered the enginewritten out, and does not format it

schemars is the one that could not be closed: the JsonSchema derives sit on Recipe and the types it holds, so the trait is on the published types themselves rather than in a signature there is a return value to change. Turning the schema feature off is the only way out of carrying two copies, which is why that feature exists.

What this does and does not claim. It claims that the declared requirement on these crates is no longer a source-compatibility surface: a consumer can depend on any version of fancy-regex it likes, and ours is an implementation detail of the graph. It does not claim the engine is interchangeable — a backtracking engine’s accepted language moves between releases, and (?<=a+)b is rejected at 0.16 and accepted at 0.19 — which is why the requirement is pinned to one minor and the differential harnesses are run against it rather than assumed.

serde, serde_json and serde_yaml do appear in public signatures and are deliberately left alone: they are 1.x, so cargo unifies every consumer onto one copy and the hazard cannot arise.

Re-exports§

pub use config::VerifierConfig;
pub use recipe::Assertion;
pub use recipe::CommandSpec as RecipeCommandSpec;
pub use recipe::Recipe;
pub use recipe::RecipeMeta;
pub use recipe::Step;
pub use recipe::RECIPE_VERSION;
pub use validation::has_errors;
pub use validation::Severity;
pub use validation::ValidationIssue;
pub use models::Recipe as ModelRecipe;
pub use models::AssertionResult as ModelAssertionResult;
pub use models::CommandSpec as ModelCommandSpec;
pub use models::RunResult as ModelRunResult;
pub use models::StepResult as ModelStepResult;
pub use result::AssertionResult;
pub use result::RunResult;
pub use result::StepResult;
pub use store::atomic_write;
pub use store::atomic_write_text;
pub use store::ensure_within_base;
pub use store::new_run_dir;
pub use store::sanitize_component;
pub use agent::build_agent_prompt;
pub use agent::parse_agent_output;
pub use agent::ParsedAgentOutput;
pub use agent::MAX_AGENT_OUTPUT_BYTES;
pub use agent::MAX_PROMPT_CONTEXT_CHARS;
pub use error::CoreError;
pub use execution::AgentDrivenMode;
pub use execution::ExecutionContext;
pub use execution::ExecutionError;
pub use execution::ExecutionMode;
pub use execution::ExecutionResult;
pub use execution::ScriptedProcessMode;
pub use execution::ScriptedPtyMode;
pub use runner::LoadedRecipe;
pub use runner::Runner;

Modules§

agent
Agent-driven execution: prompt building and bounded JSON parsing.
assertions
The eight built-in assertions (spec 003).
before_after
What changed between two runs of the same suite.
build_info
Provenance for the binary under test.
cache
Run cache — content-addressed by recipe file hash + run options.
config
Typed configuration with cascading precedence and extension preservation.
error
Typed internal errors for the crate root.
evidence
Evidence pipeline: rendering, reports, video, baselines, diff, and cache.
execution
ExecutionContext and ExecutionMode public traits (RUST-016).
junit
JUnit XML reports — one <testcase> per RunResult.
models
Canonical data models — Recipe, results, and related types.
parity
Compare two verification runs and report where they disagree.
planner
Parallel planner — deterministic ordering with bounded concurrency.
pypath
pathlib.PurePosixPath’s lexical joining and rendering.
pyregex
Python 3 re dialect for wait_for_regex.
pyrepr
One Python repr formatter, shared by every diagnostic.
pyschema
JSON Schema validation for the json_schema assertion.
recipe
Typed recipe models with flattened extension maps and legacy loading.
result
Canonical result model — mirrors termproof/models.py.
run_config
A run described by a file rather than by a command line.
runner
The concrete ExecutionContext — what actually runs a recipe.
schema
JSON Schema generation for recipes (Draft 2020-12).
selection
Choosing which recipes to run for a set of changed files.
steps
Seven built-in steps with corpus parity, ported to the InMemorySession-style Session trait.
store
Canonical artifact storage.
terminal
Terminal layer: PTY/process ownership, terminal screen, cast recording, idle, and session backends (RUST-005/006 + RUST-012 + RUST-016).
validation
Validation of recipe values before execution.
vocabulary
Screen predicates for asserting on terminal output.

Constants§

NAME
Canonical product name used by the CLI and diagnostics.
VERSION
Canonical crate/product version, inherited from the workspace manifest.

Functions§

banner
Render the canonical name version banner used by the CLI greeting.