Crate ridl_diff 

The ridl diff IR-snapshot compare engine.

The engine compares two resolved IR v2 snapshots and classifies every difference as a Change with a Category and a Verdict. It reads only the IR — never source — so the comparison is honest against exactly what a backend sees (ADR-0008 decision 14, concept note §9.1). Placement is deliberate: this crate is an engine surfaced by the ridl facade, never by ridlc, so the compiler stays a pure source→IR function (the ISO 26262 tool-qualification boundary, ADR-0008 decision 9).

The comparison has two halves. The walk ([walk]) says what structurally differs, emitting one Change per difference with a Category; the classifier (classify) says which direction that difference moved in and settles its Verdict. Splitting them is what lets a single structural category — an appended interaction, a changed timing — carry opposite verdicts depending on the direction, without the walk needing both snapshots at every emission site.

This module owns the vocabulary (Verdict, Category, Change, DiffReport), the set-level comparison (diff_sets, and diff_workspaces with the system headings of system), snapshot loading (load_ir_json), and rendering (render_text, render_json). The classification table itself is documented per category by explain, which ridl diff --explain prints.

Re-exports

pub use system::SystemChange;

pub use system::SystemHeading;

pub use system::diff_systems;

Modules

system

ridl diff at the system (rsdl reference §14): the changes to a lowered system that are not contract changes.

Structs

Change

One difference between two snapshots, with an honest path into the IR and the rendered before/after values where they apply.

DiffReport

The result of a comparison: every change and the report-level verdict (the maximum verdict over the changes; Verdict::Identical when there are none).

Enums

Category

The kind of a single difference. The walk emits the structural categories; the classifier maps them to directional verdicts.

LoadError

An error loading an .ir.json snapshot.

Verdict

The compatibility verdict of a change or of a whole report — ordered so Breaking > Compatible > Identical and a report’s verdict is the maximum over its changes.

Constants

CATEGORIES

Every category, in the order --explain lists them when asked for an unknown one.

Functions

absence_refused

Whether a reader built against new_set refuses a payload in which the field member of struct container, in package package, is absent — the rule that makes an appended field breaking for its type (driftsys/ridl#598). context holds packages that references resolve against without being compared, such as ridl.std. false when container is not a struct of that package. The ridl check desk check reads it to say so in its RIDL-407 message for an append that also sits beside a moved sibling.

category_from_word

Parses the snake_case word a report prints back into its category, so ridl diff --explain <category> takes exactly what the report shows.

category_word

The stable snake_case word for a category — the single source of truth for both renderers and for ridl diff --explain, which takes a category exactly as the report prints it.

classify

Classifies one change against the two snapshots it was drawn from.

diff_packages

Compares two resolved packages. Matched packages share a name; the new package’s name is used as the path prefix.

diff_sets

Compares two sets of resolved packages, matching by package name. A package present only on one side is a Category::DeclRemoved or Category::DeclAdded; matched packages are walked pairwise.

diff_sets_in

diff_sets, with context: packages that a type reference resolves against without being compared. The ridl CLI passes the built-in ridl.std here, so a struct field appended with a ridl.std type is judged by that type’s declaration (driftsys/ridl#598).

diff_workspaces

Compares two workspaces at the system (rsdl reference §14): the packages by the ridl categories, exactly as diff_sets does, and — when both sides carry a lowered system — the system’s placement and composition changes, which carry no verdict. A system on one side only is not compared: there is nothing to compare it against.

explain

The rule row for a category: the classification table of ADR-0008 decision 14 as text. This is the CI-facing documentation of record until the E4 error index publishes it.

heading

The heading a category’s changes are grouped under in the text report, or None for a category listed plainly. One heading exists: “compatible on the wire, visible in source”, for a change that exits 0 but that a consumer sees in its source — an interface renamed on its number changes the generated identity-table names in both wire backends, and an interface leaving a service’s set stops the service.member addresses of that interface resolving under the service. Each such category’s --explain text states its own consequence; the JSON report carries the category word and no heading field.

load_ir_json

Loads an .ir.json snapshot written by ridl build --emit ir-json — canonical protobuf JSON, read through the one reader every surface shares (ADR-0014 decision 1).

render_json

Renders a report as machine-readable JSON with the stable schema {"verdict", "changes": [{"path", "category", "verdict", "before", "after"}]}.

render_text

Renders a report as a human-readable summary: the report verdict on the first line, then one indented line per change. A change whose category has no heading is listed first, in report order; then each heading is printed once, as its own line ending in a colon, followed by the changes under it, in report order. Headings come in CATEGORIES order.