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, and interface numbers within each unit ([walk::Matching]). A package present only on the new side is a Category::DeclAdded; matched packages are walked pairwise. A package present only on the old side is a Category::DeclRemoved when its whole unit is gone from the new side, and is walked declaration by declaration when the unit is still there, so that an interface whose number moved to another package of the unit is Category::InterfaceRenamed and one the unit retired is Category::InterfaceRetired.

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.